Introduction

Microchip TCP/IP Stack Help
Contents | Index
Next
Introduction
Welcome to the Microchip TCP/IP Stack!

The Microchip 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.

Updates

The latest version of the Microchip TCP/IP Stack is always available at [image] http://www.microchip.com/tcpip. New features are constantly being added, so check there periodically for updates and bug fixes.

Wi-Fi® is a registered trademark of the Wi-Fi Alliance.

Topics
Name | Description
Getting Help | Where to get help for the TCP/IP Stack
Directory Structure | Describes where to find files in the TCP/IP Stack.
Introduction
Microchip TCP/IP Stack 5.36.2 - July 14, 2011
Copyright © 2011 Microchip Technology, Inc. All rights reserved.


Getting Help

Contents | Index | Home
Previous | Up | Next
Getting Help

The TCP/IP Stack is supported through Microchip's standard support channels. If you encounter difficulties, you may submit ticket requests at [image] 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 [image] http://forum.microchip.com.

Microchip also offers embedded network classes through Regional Training Centers. For more information, visit [image] http://www.microchip.com/rtc.

Introduction > Getting Help


Directory Structure

Contents | Index | Home
Previous | Up | Next
Directory Structure

The TCP/IP Stack comes with many files, tools, documents, and project examples. Before getting started, take a moment to familiarize yourself with the directory structure so that you may find what you need quickly. Installing the stack will produce the following structure:

Several demonstration projects are installed into the TCPIP directory in the default Microchip Solutions v20xx-xx-xx directory. In your projects, you may wish to write your application code in a project folder located in the same place as the demo project folders. For more information about specific demos, see the list of demo projects in this help file. These project folders may contain additional subdirectories:

  • A Configs subdirectory will contain alternative copies of the TCPIPConfig.h and HardwareProfile.h configuration files, pre-configured to work with different demo boards. The default copies of these files in the demo folder will include one of these alternative files based on a macro defined in the demo project.
  • An SSLKeys subdirectory will contain sample security keys and certificates.
  • A WebPages2 subdirectory will contain sample web pages for use with the MPFS2 file system.
  • An MPLAB.X project folder contains the MPLAB X project files for the demo.
  • A Precompiled Hex subdirectory contains precompiled hex images of the demo project.

Other stack-specific folders include are:

  • The Microchip folder contains stack files and components.
  • The Include sub-folder under the Microchip folder contains header files for Microchip stack and library solutions. The TCPIP Stack folder in the Include folder contains headers for the TCP/IP Stack.
  • The TCPIP Stack folder in the Microchip folder contains C source files, documentation, and stack utilities.
    • The Demo Board Files subdirectory contains information about the different demo boards that can run the TCP/IP stack.
    • The Utilities subdirectory contains PC-based utilities that can help when using the stack. See the Software section for more information. The source code for the Microchip TCP/IP Discoverer, the MPFS2 tool, and the MPFS library is located in the Source subdirectory in the Utilities directory.

In most cases, it will not be necessary to modify source or header files in the Microchip directory.

Introduction > Directory Structure


MICROCHIP IS WILLING TO LICENSE THE ACCOMPANYING SOFTWARE AND DOCUMENTATION TO YOU ONLY ON THE CONDITION THAT YOU ACCEPT ALL OF THE FOLLOWING TERMS

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. BY DOWNLOADING AND INSTALLING THE SOFTWARE, LICENSEE AGREES TO BE BOUND BY THE TERMS OF THIS AGREEMENT.

NON-EXCLUSIVE SOFTWARE LICENSE AGREEMENT FOR ACCOMPANYING MICROCHIP SOFTWARE AND DOCUMENTATION

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, 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").

The Software and Documentation are licensed under this Agreement and not sold. U.S. copyright laws, international copyright treaties, and other intellectual property laws and treaties protect the Software and Documentation. Microchip reserves all rights not expressly granted to Licensee in this Agreement.

(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.

(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 no Open Source Components (defined in Section 5 below) are incorporated into such Software in such a way that would affect Microchip’s right to distribute the Software with the limitations set forth herein and provided that Licensee clearly notifies Third Parties regarding 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") 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");

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. 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, and Microchip hereby represents and warrants that the licenses granted to such Open Source Components will be no less broad than the license granted in Section 1. 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.

a. Licensee will ensure Third Party compliance with the terms of this Agreement, and will be liable for any breach of this Agreement committed by such Third Party.

b. Licensee will not: (i) engage in unauthorized use, modification, disclosure or distribution of Software or Documentation, or its derivatives; (ii) use all or any portion of the Software, Documentation, or its derivatives except in conjunction with Microchip Products or Third Party Products; or (iii) reverse engineer (by disassembly, decompilation or otherwise) Software or any portion thereof.

c. Licensee may not remove or alter any Microchip copyright or other proprietary rights notice posted in any portion of the Software or Documentation.

d. 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 product liability claims, directly or indirectly arising from or related to: (i) the use, modification, disclosure or distribution of the Software, Documentation, or any intellectual property rights related thereto; (ii) the use, sale and distribution of Licensee Products or Third Party Products; and (iii) breach of this Agreement. THIS SECTION 3(d) STATES THE SOLE AND EXCLUSIVE LIABILITY OF THE PARTIES FOR INTELLECTUAL PROPERTY INFRINGEMENT.

(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 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 petition for 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 ("Proprietary Rights") 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). Further, copies and derivative works will be considered works made for hire with ownership vesting in Microchip on creation. To the extent such modifications and derivatives do not qualify as a "work for hire," Licensee hereby irrevocably transfers, assigns and conveys the exclusive copyright thereof to Microchip, free and clear of any and all liens, claims or other encumbrances, to the fullest extent permitted by law. Licensee and Third Party use of such modifications and derivatives is limited to the license rights described in Sections 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. LICENSEE AND THIRD PARTY ASSUME THE ENTIRE RISK ARISING OUT OF USE OR PERFORMANCE OF THE SOFTWARE AND DOCUMENTATION PROVIDED UNDER THIS AGREEMENT.

(11) Limited Liability. IN NO EVENT WILL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER 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.

LICENSEE ACKNOWLEDGES AND AGREES THAT IT IS SOLELY RESPONSIBLE FOR THE LICENSEE PRODUCTS AND THIRD PARTY PRODUCTS, INCLUDING DETERMINING WHETHER SUCH PRODUCTS INFRINGE A PATENT, COPYRIGHT OR OTHER PROPRIETARY RIGHT OF ANY THIRD PARTY. LICENSEE AGREES THAT MICROCHIP HAS NO OBLIGATION TO INDEMNIFY OR DEFEND LICENSEE IN THE EVENT THAT A THIRD PARTY MAKES A CLAIM REGARDING LICENSEE PRODUCTS OR THIRD PARTY PRODUCTS.

(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 in the courts of the State of Arizona. The parties agree to waive their rights to a jury trial in actions relating to this Agreement. If either the Microchip or Licensee employs attorneys to enforce any rights arising out of or relating to this Agreement, the prevailing party will be entitled to recover its reasonable attorneys' fees, costs and other expenses. 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 the Microchip. Microchip’s authorized representatives will have the right to reasonably inspect Licensee's premises and to audit Licensee's records and inventory of Licensee Products in order to ensure Licensee's adherence to the terms of this Agreement. 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 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. Neither this Agreement nor any rights, licenses or obligations hereunder, may be assigned by Licensee without the prior written approval of Microchip except pursuant to a merger, sale of all assets of Licensee or other corporate reorganization, provided that assignee agrees in writing to be bound by the 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 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) 2011 Microchip Technology Inc. All rights reserved.

License Rev. No. 03-060111


Release Notes

Contents | Index | Home
Previous | Next
Release Notes
******

Microchip TCP/IP Stack Version Log:

******
Remarks

Please file bug-reports/bug-fixes at http://support.microchip.com/ or post to the Microchip TCP/IP -> Ethernet Forum at http://forum.microchip.com/ Look for stack updates at http://www.microchip.com/mal/

******

v5.36.2 July 2011

******

Changes:

  1. Removed the Google PowerMeter and Google PowerMeter EZConfig demos. Google, Inc. has deprecated Google PowerMeter and has expressed the intent to remove access to it on September 16, 2011. To obtain Microchip Technology's Google PowerMeter reference implementation, you can download the June 2011 Microchip Application Libraries archived release from www.microchip.com/mal.
  2. Modified the Energy Monitoring demo to remove Google PowerMeter functionality. The demo will still display measured power data on its internal web page.
  3. Updated the TCP/IP Stack Performance table to use the testing methodology from previous releases. More information is available in the TCP/IP Stack Help file.
  4. gSnmpNonMibRecInfo[] has been moved from snmp.c file to CustomSNMPApp.c file and SNMP_MAX_NON_REC_ID_OID macro has been moved from snmp.h file to CustomSNMPApp.c file. gSnmpNonMibRecInfo[] is used to list the static variables parent OID strings which are not part of mib.h file. This structure is used to restrict the access to the SNMPv3 objects from SNMPv2c and SNMPv1 version requests. Macro STACK_USE_SMIV2 is used to support gSnmpNonMibRecInfo[] with MODULE-IDENTITY number. For V5.31 STACK_USE_SMIV2 need to commented.
  5. Removed the SPI2CON register freeze-on-halt bit macro from the SPIFlash, RAM, and EEPROM driver files to provide compatibility with C32 v2.00.

Fixes:

  1. Removed the MPFSImg2 files from the MPLAB X C18/C30 projects so that the projects will compile. Disabled MPFSImg2.c for PIC32 Explorer 16 projects.
  2. Added a heap and minimum stack size for the PIC32 Ethernet Starter Kit MPLAB X project.
  3. The TCP/IP Stack Help File's performance table has been updated using the same test procedure used in previous releases.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. LCDBlocking.c timing for the LCD_E_IO enable signal is too fast to meet published data sheet limits for various LCD controllers when compiling for a PIC32 running at > 43MHz. Despite this potential timing violation, the LCD does normally work correctly on the precompiled PIC32 demos for the Explorer 16 at 80MHz.
  4. For PIC32 implementations, depending on the configuration, it is possible that the MACGetFreeRxSize() returns a value greater than 64 KB. For backward compatibility reasons the stack uses a 16 bit value to check the returned value and it won't work corretly.
  5. Limiting the number of UDP sockets to 8 in the stack demos may prevent SNMP trap functionality. If this occurs, you can increase the MAX_UDP_SOCKETS definition in TCPIPConfig.h to 10 (if your system will support the increased data memory usage) to fix this issue.
  6. The SNMP mib file's date and version parameter does not match the date/version of the current stack release.

******

v5.36 2 June 2011

******

Changes:

  1. Because of changes to the SHOUTcast server configuration, the Internet Radio demo is no longer functional. This demo has been retained in the stack distribution to provide a TCP/IP code example.
  2. The UDP module will now perform address resolution and DNS querying automatically. As a result, the UDP module APIs have changed. The UDPOpenEx function provides this additional functionality. Please consult the TCP/IP Stack Help File's "Stack API > UDP" topic for more information.
  3. The UDPOpen macro has been added to conform to the legacy UDPOpen interface.
  4. The Announce, BerkeleyAPI, DHCP client/server, DNS client/server, NBNS, Reboot, SNMP, SNTP, TFTPc, UDPPerformanceTest, and ZeroConf modules have been updated to use the new UDP API. The iPerf demo has also been updated.
  5. The MPFS Classic and HTTP(1) modules have been removed from the stack. Function- ality to support these modules has also been removed from the TCP/IP Stack software tools. MPFS2 and HTTP2 are still supported.
  6. The UARTConfig demo module has been updated to upload MPFS2 images to the demo board in place of MPFS Classic images.
  7. To facilitate linking on PIC18 platforms, the number of UDP sockets in demo projects has been reduced from 10 to 8.
  8. The SNMP Stack application and mib2bib.jar PC utility now both support 1024 dynamic IDs.
  9. SNMP_DEMO_TRAP is a new dynamic variable added to the snmp.mib file to support SMIv2 with TRAPv2. This will correct a previously existing issue viewing traps with the iReasoning MIB browser. As per those changes, the mchp.mib file has been modified to support the SMIv2 standard. This mib includes MODULE-IDENTITY which will provide MICROCHIP and MIB information. snmp.mib also includes MODULE-IDENTIY(1), a new number (1) to the existing OID after ENTERPRISE-ID(17095).
  10. Added a preprocessor check that will include the ultoa function if a version of the C32 compiler earlier than 1.12 is used.
  11. Modified the WiFi module to use separate retry counters for AdHoc and Infrastructure modes.
  12. Modified Berkeley API module to accept IPPROTO_IP as a valid protocol for the socket function. The code will determine the protocol type from the socket type (datagram or stream).
  13. Created MPLAB X projects corresponding to most MPLAB 8 projects and configurations. These projects are located in the MPLAB.X subfolder in the associated demo project directory. The MPLAB X import wizard can be used to create MPLAB X projects from MPLAB 8 projects that don't have an analogue in the new demo project folders.
  14. Added project support for the dsPIC33E and PIC24E architectures.
  15. All TCP/IP Stack demo projects have been moved to the "TCPIP" subdirectory in the stack installation directory.
  16. Created Java versions of several TCP/IP tools to provide cross-platform support. The TCP/IP Configuration Wizard has not been ported to Java; thus, it is only available for Windows users.
  17. To prevent issues with path length, MPLAB 8 project names have been changed. A list of the abbreviations used in the project names is available in the MAL help folder (Microchip Solutions/Microchip/Help/Abbreviations.htm). The names of the HardwareProfile and TCPIPConfig configuration files have been abbreviated as well.
  18. Changed the configuration inclusion macros used by the TCP/IP Stack demo projects to match the terms used in the project/configuration names.
  19. The "Alternative Configurations" subfolders in most demo projects has been renamed to "Configs."
  20. Added a Google PowerMeter demo for use with the PIC18F87J72 Energy Monitoring PICtail.
  21. The Web Preview tool is no longer included with the stack.

Fixes:

  1. Fixed a DHCP Server (DHCPs.c) lease leak problem that would occur when STACK_USE_ZEROCONF_LINK_LOCAL was defined. This problem would have resulted in the DHCP server stop giving out any leases until being rebooted.
  2. Updated the PIC32MX6XX/7XX external PHY SMSC 8720LAN reference design.
  3. Fixed bug with window expecting MACGetFreeRxSize() to return values < 32KB.
  4. Fixed a type casting bug with the CalcIPChecksum function that would cause an incorrect TX checksum if the checksum value overflowed again after adding the carry bits to the checksum value.
  5. Fixed a bug in the AutoIP module that may have prevented the module from correctly defending its own address.
  6. Added a check to the Announce module to ensure the MAC layer is linked before attemping to transmit an Announce message.
  7. Fixed a bug in the ETH97J60 MACPut function.
  8. Added an additional preprocessor check in a debug menu setting in WF_Spi.c to prevent a build error.
  9. Added a fix to the Google PowerMeter demo code to restore SNTP timestamp sourcing if SNTP is enabled. Previously, it would be overwritten by a possibly invalid HTTP timestamp.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. LCDBlocking.c timing for the LCD_E_IO enable signal is too fast to meet published data sheet limits for various LCD controllers when compiling for a PIC32 running at > 43MHz. Despite this potential timing violation, the LCD does normally work correctly on the precompiled PIC32 demos for the Explorer 16 at 80MHz.
  4. For PIC32 implementations, depending on the configuration, it is possible that the MACGetFreeRxSize() returns a value greater than 64 KB. For backward compatibility reasons the stack uses a 16 bit value to check the returned value and it won't work corretly.
  5. Limiting the number of UDP sockets to 8 in the stack demos may prevent SNMP trap functionality. If this occurs, you can increase the MAX_UDP_SOCKETS definition in TCPIPConfig.h to 10 (if your system will support the increased data memory usage) to fix this issue.
  6. The SNMP mib file's date and version parameter does not match the date/version of the current stack release.

******

v5.31 19 October 2010

******

Changes:

  1. Reorganized demo projects. The TCPIP ENCX24J600 Demo App, TCPIP PIC32 ETH Demo App, and TCPIP WiFi Demo App projects in stack versions 5.25 and prior have all been merged into the TCPIP Demo App folder. All four of these projects were almost identical to each other, with the primary difference being the network interface controller the projects were preconfigured to support. In this 5.31 TCP/IP Stack release, each hardware combination now has its own MPLAB IDE project in the TCPIP Demo App folder.
  2. Reorganized HardwareProfile.h and TCPIPConfig.h structure for the TCPIP Demo App, TCPIP Google PowerMeter Demo App, and TCPIP WebVend App projects. Now, instead of having one massive HardwareProfile.h file that supports a multitude of hardware platforms simultaneously, simple individual hardware profiles have been created for specific hardware combinations and placed in the "Alternative Configurations" sub-folder. The correct hardware profile or TCPIP config file is selected by #including "HardwareProfile.h" or "TCPIPConfig.h" as in previous stack versions. However, the active hardware profile or config file from the Alternative Configurations folder is selected by a preprocessor macro defined in the MPLAB project settings (passed on the command line to the compiler).
  3. Added HTTP_SAVE_CONTEXT_IN_PIC_RAM option to TCPIPConfig.h (HTTP2 server module). This option, when enabled, will increase HTTP2 server performance when servicing multiple simultaneous connections at the expense of using more PIC RAM.
  4. Added automatic TPIN+/- polarity swapping logic to ETH97J60.c driver for PIC18F97J60 family devices. Some 3rd party Ethernet switches, routers, and end devices have their TX+/- pins wired backwards such that the remote TX+ signal connects to the PIC TPIN- pin and the remote TX- signal connects to the PIC TPIN+ pin. Because 10BaseT Ethernet signaling is polarized and the PIC18F97J60 family does not implement an auto-polarity feature, this normally prevents all RX communications with these non-IEEE 802.3 compliant link partners. To work around this incompatibility, it is possible to implement circuitry to swap the RX+ and RX- signals before reaching the TPIN+ and TPIN- pins. The PICDEM.net 2 Rev 6 reference design includes this necessary circuitry (U6, U7, R54, and RX_SWAP GPIO output pin from PIC). This stack version automatically controls the RX_SWAP signal based on the ETH_RX_POLARITY_SWAP_TRIS and ETH_RX_POLARITY_SWAP_IO definitions in HardwareProfile.h. If these macros are undefined, then the automatic polarity swapping feature is disabled in the ETH97J60.c driver.
  5. Added portable LFSRRand() and LFSRSeedRand() public functions to Helpers.c and removed all references to C rand() and srand() functions. The C rand() function returns a 15 bit integer on 8 and 16 bit PICs, but a 31 bit integer on PIC32s. The LFSRRand() function returns a 16-bit integer, regardless of which PIC you are using.
  6. Added support for various SST/Microchip brand SST25xxxxx SPI Flash chips to SPIFlash.c driver. Previously only devices supporting the Auto Address Increment (AAI) Word Program opcode (0xAD) would work. Now, devices such as the SST2525VF010A should work, which require the AAI Byte program opcode (0xAF) instead.
  7. Removed support for Spansion brand SPI Flash chips in the SPIFlash.c driver. If your application is already using one of these devices, continue to use the SPIFlash.c/.h files from TCP/IP Stack 5.25. These older files are API compatible with the current version, so can be dropped in by simply overwriting the SPIFlash.c and SPIFlash.h files.
  8. Removed a -4 offset from the advirtised TCP Maximum Segment Size option (MSS) and TCP_MAX_SEG_SIZE_RX configuration value in TCP.c. The default TCP MSS advertised is now 536 instead of 532.
  9. For Wi-Fi projects in the TCPIP Demo App folder, changed MY_DEFAULT_LIST_RETRY_COUNT to WF_RETRY_FOREVER instead of 3. This changes default connection behavior to keep trying to connect instead of just trying 3 times which makes more sense for demonstration.
  10. Changed WF_Connect() beacon timeout to 40.
  11. IFConfig command in TCPIP WiFi Console Demo App modified to return application-perspective MAC address from the AppConfig structure, and not the Wi-Fi serialized MAC address (they may not match if user desired custom MAC).
  12. Updated the TCP/IP Configuration Wizard. The user can now configure wireless settings and stack settings seperately. Because of the changes to the TCPIPConfig.h file, the user must now select the specific copy of TCPIPConfig.h (or any of its variants) instead of selecting a project directory. Added the ability to select WF_RETRY_FOREVER in the Wi-Fi configuration settings. Added a selection parameter for BSD socket count. Added validation to check for the proper number of Berkeley sockets and TCP performance test sockets in the socket configuration screen (Advanced Settings) if either of these features are enabled. Added the ability to create sockets of the same type with different TX/RX buffer sizes in the socket configuration screen.
  13. Updated the TCPIP WebVend Demo App to support Wi-Fi in several configurations.
  14. Modified the Google PowerMeter demo to automatically determine the date/time from the HTTP module if the date/time cannot be obtained from the SNTP module.
  15. Added a new Google Map project example to the Combo Demos folder. This example runs on a PIC24FJ256DA210 Development Board + Fast 100Mbps Ethernet PICtail Plus (or Ethernet PICtail Plus) + Truly 3.2" 240x320 display, TFT_G240320LTSW_118W_E (or Powertip 4.3" 480x272 display, PH480272T_005_I11Q). It also can run on the PIC32 Multimedia Expansion Board + PIC32 Ethernet Starter Kit. This demo connects to the Internet, sends an HTTP query for a specific map tile to the Google Static Maps API, and then displays the compressed tile to the graphics display. For more information, see the "Getting Started - Running the Graphics Google Map Demo.htm" file in the Combo DemosGoogle Map folder.
  16. Added preliminary SNMPv3 module. This module, enabled with the STACK_USE_SNMPV3_SERVER option in TCPIPConfig.h, implements the Simple Network Management Protocol, version 3. Among other things, SNMPv3 adds secure authentication and cryptographic privacy as compared to SNMPv2C. This implementation currently only supports AES encryption (no DES support). It also has only been tested with the PIC32 Ethernet Starter Kit (TCPIP Demo App - C32 - PIC32_ENET_SK_DM320004_INTERNAL_ETHERNET.mcp MPLAB IDE project). SNMPv3 on PIC18, PIC24, and dsPIC platforms are not supported at this time. Because AES encryption has specialized United States export requirements, this TCP/IP Stack release does not include the required AES library to enable SNMPv3. To obtain the needed AES library, you must purchase SW300052 v2.6 or later. Older v2.5 and previous versions include AES related files on them, but do not include the new AES files required by SNMPv3. For more information on using SNMP, refer to the TCP/IP Stack Help (Demo Information -> Available Demos -> TCPIP Demo App -> Demo Modules -> Network Management (SNMP) Server).
  17. Altered the SaveAppConfig() function in MainDemo.c to store a more robust signature to EEPROM/SPI Flash when saving the AppConfig structure. In v5.25 and prior stack versions, when EEPROM or SPI Flash memory was available, the stack would automatically write a one byte marker character to address 0x000000 in the EEPROM/Flash indicating if a valid AppConfig structure was stored in the non-volatile memory. This resulted in the EEPROM/Flash contents being organized like the following: Address Data Contents =================== ============================================== 0x000000: Marker Byte 0x000001: AppConfig structure MPFS_RESERVE_BLOCK: Start of MPFS/MPFS2 image containing web pages In this stack version, EEPOM/Flash contents will now contain: Address Data Contents =================== ============================================== 0x000000: Length of AppConfig structure (16-bit integer) 0x000002: IP checksum of the AppConfig default values, as defined in TCPIPConfig.h and WF_Config.h (16-bit integer). 0x000004: IP checksum of the subsequent EEPROM/Flash bytes of the AppConfig values. 0x000006: AppConfig structure MPFS_RESERVE_BLOCK: Start of MPFS/MPFS2 image containing web pages

The additional checkums allow automatic detection to occur if you change one of the values in TCPIPConfig.h or WF_Config.h that affects AppConfig. If you change one of the values in code, then upon boot up, the application will automatically detect this change and start using the values that you selected in code. If, at run time, you decide to change the AppConfig values and commit the changes to EEPROM/Flash, then the stack will subsequently use the run-time saved values on future reboots. The checksum at offset 0x000004 ensures that if any corrupted AppConfig contents are found in EEPROM/Flash (ex: power is lost between writing the signature structure and actual AppConfig structure, or code unintentionally overwrites something in the AppConfig memory area), then the original defaults defined in TCPIPConfig.h and WF_Config.h will be used instead of the corrupted values. This EEPROM/SPI Flash change affects all projects except TCPIP Internet Radio App, TCPIP Internet Bootloader App, and all PIC32 Starter Kit projects since these projects do not have or use external EEPROM or SPI Flash memory.

Fixes:

  1. Fixed a UDP bug in which a transmitted packet would have been addressed to the wrong destination node if the UDP socket received a broadcast packet from a different remote node from the last received packet, but using the same source port number as the last received packet. The FindMatchingSocket() function in UDP.c will now always change the local socket parameters to send to the most recent remote node's unicast IP address, regardless of if the last received packet was addressed to a multicast or broadcast destination. Thanks go to Billy Walton for reporting this erroneous behavior. If you wish to change the destination IP/MAC addresses or port number for a UDP packet that you are ready to send, write the new parameters to the UDPSocketInfo[SocketHandle] global structure before calling UDPFlush(). This structure contains remoteNode and remotePort parameters for the remote IP address/MAC address and remote UDP port, respectively. You can also read these values to obtain the remote addressing parameters for the last received packet on the given UDP socket. Note that "SocketHandle" refers to the UDP socket handle returned by the UDPOpen() API, not the literal string "SocketHandle".
  2. Fixed ADC state save/restore bug in GenerateRandomDWORD() function in Helpers.c. PIC24, dsPIC, and PIC32 platforms require the ADC ON/ADON bit to be cleared before modifying certain other ADC register contents.
  3. Fixed an ENC28J60 MAC/MII register write timing violation when using a PIC24H or dsPIC at over 33MIPS. There was inadequate Chip Select hold time provided, violating the 210ns minimum specified in the ENC28J60 data sheet. This violation may have resulted in certain devices losing the ability to receive packets (due to the MARXEN bit, MACON1<0>, getting cleared unintentionally).
  4. Fixed an ENCX24J600.c driver bug in which operating at 100Mbps with the ENC424J600/624J600 Ethernet controller, it would be possible for the MACGetHeader() function to issue a Reset() operation under rare circumstances. The PIC would reset whenever the PHY detected an illegal symbol during 4B5B decoding but guessed the correct 4B symbol such that no data corruption or CRC error occurred. This condition results in a valid packet being received but with the Received Ok Receive Status Vector bit being clear (RSV<23> == 0). This issue would become more probable when using very long Ethernet cables (ex: 100 meters) and receiving a lot of data.
  5. Fixed a TCP bug in which calling TCPDisconnect() to close a connection when the remote node's RX window was 0 bytes would have caused the stack to enter an infinite loop sending duplicate ACK packets.
  6. Fixed Wi-Fi bug that caused assert condition if too many management messages were being received during data traffic.
  7. Fixed Wi-Fi bug that caused WF_EVENT_CONNECTION_RESTABLISHED event case to send the wrong notification to the app.
  8. Fixed Wi-Fi bug that caused assert failure with Scratch move failure.
  9. Fixed Wi-Fi bug in WF_CAGetChannelList() and WF_CAGetSecurity that caused failure.
  10. Fixed Wi-Fi EasyConfig bug that required development boards to be manually reset even after new network was selected.
  11. Fixed MRF24WB0 bug that caused assert if invalid WPA/WPA2 key was entered.
  12. Fixed Wi-Fi power management bit behavior in PS-Poll frame that was causing some AP’s to never send data or disconnect when in power save mode.
  13. Fixed a TCP bug in which attempting to open a client TCP socket to a remote server, specified by IP address (not DNS address), that was offline, but who's MAC address was already cached by the ARP client, would result in endless back-offs. For example, when attempting to contact the remote node (that was not responding), the TCP module would have transmitted a SYN at time T=0 seconds, T=1s, T=3s, T=7s, T=15s, T=31s, T=63s, T=127s, T=255s, etc. The exponential back-off between retransmissions would grow indefinitely until the retransmission interval would have grown so large that effectively no-retransmissions would be occurring. Assuming the application wasn't written with its own timeout to prevent endless waiting, this would prevent the socket from automatically establishing the connection to the remote server once the server came back online. With this TCP fix, the exponential back off now saturates after TCP_MAX_RETRIES (5) back offs and continues to retransmit using the same interval. By default, this means SYN transmissions will occur at T=0 seconds, T=1s, T=3s, T=7s, T=15s, T=31s, T=63s, T=95s, T=127s, etc. After 5 back-offs the retransmission interval stops growing and stays constant at 32 seconds.
  14. Fixed an RSA computation bug that would cause the RSA module to never complete if you attempted to compute y = x^e % n where e = 3 (or similar number < 256 with only 0, 1, or 2 bits set). Thanks go to Kevin Maidment for pointing this error out and suggesting a solution. Note, that this fix to RSA.c is not distributed with the ordinary TCP/IP Stack due to United States export restrictions. To get this fix, you must repurchase SW300052. This fix is included in SW300052 v2.6 or later. If you don't have CD media to identify the SW300052 version that you have, you can test the RSA.c file that you have. RSA.c in SW300052 v2.6 has a CRC32 checksum of 0x91F66711. RSA.c in v2.5 and prior had a checksum of 0xB1E8B0CC.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. LCDBlocking.c timing for the LCD_E_IO enable signal is too fast to meet published data sheet limits for various LCD controllers when compiling for a PIC32 running at > 43MHz. Despite this potential timing violation, the LCD does normally work correctly on the precompiled PIC32 demos for the Explorer 16 at 80MHz.

******

v5.25 07 May 2010

******

Changes:

  1. Added support for the Microchip MRF24WB0 802.11 WiFi controller (module part number MRF24WB0MA). This product is intended as a backwards compatible, drop in replacement to the ZG2100. The MRF24WB0MA should work with previous TCP/IP Stack versions as if it were a ZG2100M, but when the MRF24WB0MA is used with this (5.25) and future TCP/IP Stack versions, feature improvements inside the MRF24WB0 allow the TCP/IP Stack code/RAM size to be smaller and run faster.
  2. Dropped support for the ZeroG ZG2100 802.11 WiFi controller. Applications that must stay with this device should continue to use TCP/IP Stack version 5.20b or earlier. All new projects or preexisting projects undergoing updates should be developed with the MRF24WB0 instead.
  3. The WiFi connection management state machines now run on the MRF24WB0 instead of the PIC host, freeing up code and data space. Connection profiles can be created and the connection algorithm fine-tuned by the PIC application. In the WiFi demos see the WF_Connect function in MainDemo.c for an example of how to configure and then establish a WiFi connection. The programming model has changed to an API model which is documented in 'TCPIP Stack Help.chm'.
  4. Changed "VERSION" macro definition in TCPIP.h to "TCPIP_STACK_VERSION". "VERSION" is overly generic and will likely conflict with other identical tokens one may use in their application code or source libraries.
  5. Added support for the PIC24FJ256GA110, PIC24FJ256GB110 and PIC24FJ256GB210 PIMs for the Explorer 16. Note that when using the PIC24FJ256GA110 general purpose PIM, the Ethernet PICtail Plus, Fast 100Mbps Ethernet PICtail Plus, MRF24WB0MA Wi-Fi PICtail Plus, or other SPI PICtail daughter board should be installed in the middle SPI2 slot of the Explorer 16, not the ordinary topmost SPI1 slot used by other PIMs, including the PIC24FJ256GB110 and PIC24FJ256GB210 ones. The software is set up to use SPI2 for the PIC24FJ256GA110 PIM to avoid incompatibilities with silicon revision A3, which does not allow the SCK1 pin to be configured as a PPS output.
  6. Added support for the PIC24FJ256DA210 Development Board.
  7. Added TFTPUploadRAMFileToHost(), TFTPUploadFragmentedRAMFileToHost() and TFTPGetUploadStatus() APIs to the TFTPc.c file. These APIs provide a very simple means of uploading a whole file to a remote TFTP server without requiring a great deal of application state machine logic. These APIs require the DNS client module to be enabled (STACK_USE_DNS must be defined, in addition to STACK_USE_TFTP_CLIENT).
  8. Added a dummy DNS Server module. This server always sends the local IP address in response to all queries received. When using the PIC DHCP server, its purpose is to allow a user to type anything into a web browser (ex: http://asdf/) and still receive the web page provided by the PIC, much as a hotel or airport WiFi router will serve to you before you've paid or agreed to the network's terms of service. This DNS server module is implemented in DNSs.c, requires one UDP socket, and is enabled via the STACK_USE_DNS_SERVER option in TCPIPConfig.h.
  9. Changed SPIFlash.h file defaults to target an SST SPI Flash with 4096 byte sectors instead of a Spansion Flash with 65536 byte sectors. These new defaults are, among other reasons, in support of the PIC24FJ256DA210 Development Board, which has an SST SST25VF016B on it.
  10. Made TCP Keep-Alive packets consistently get sent TCP_KEEP_ALIVE_TIMEOUT (default 10 seconds) after the last socket TX or RX activity. In earlier stack versions, if the local node transmitted some data and then let the socket go idle, the first Keep-Alive packet sent would use the TCP_START_TIMEOUT_VAL (default 1 second) timer value before getting sent. While benign in terms of application behavior, these faster than normal keep-alive transmissions were distracting when viewed in Wireshark or other packet capture tools.
  11. Disabled STACK_USE_DYNAMICDNS_CLIENT option in TCPIPConfig.h by default for the TCPIP Demo App and TCPIP ENCX24J600 Demo App projects. This option was enabled by default in earlier stack releases. This was done to save code size and allow out-of-box compilation on devices with 128KB of Flash when not using compiler optimizations. The TCPIP PIC32 ETH Demo App project continutes to have this option enabled by default.
  12. Added SNMP v2 TRAP PDU format. Macro SNMP_STACK_USE_V2_TRAP is used to enable the SNMP v2 trap format. New API function SNMPV2TrapDemo() is included to support more than one variable binding to the SNMPv2 TRAP. This API can be used for a single SNMPv2 TRAP variable varbind and is part of CustomSNMPApp.c. A multiple variable binding demo can be enabled MainDemo.c. One should not enable both SNMPTrapDemo and SNMPV2TrapDemo simultaneously. Global flag "gSetTrapSendFlag" is used to indicate the start and end of SNMPv2 trap varbinds. If gSetTrapSendFlag is FALSE, then very next variable varbind for the SNMPv2 TRAP, is the last or only one variable varbind. If gSetTrapSendFlag is TRUE, then there is another variable varbind available to be part of the SNMPv2 TRAP PDU.
  13. Added support for PIC32MX6XX/7XX external PHY's: SMSC 8700LAN and National DP83640.
  14. Added schematics and BOM for the PIC32 Ethernet Starter Kit.
  15. Added the Google PowerMeter demo project. Consult the "Reference Implementation for Google PowerMeter.chm" help file for more information.
  16. Modified the SSL and TCP modules to create the TCPStartSSLClientEx function. This function will enable the SSL module to store supplementary data (currently only SSL Certificate Public Keys) in a structure.
  17. Moved the HTTP_PORT, HTTPS_PORT, HTTP_MAX_DATA_LEN, and HTTP_MIN_CALLBACK_FREE macros from HTTP2.c to TCPIPConfig.h.

Fixes:

  1. The SPIFlashEraseSector() function in the SPIFlash.c file incorrectly erased the sector specified by the current write pointer (set by calling SPIFlashBeginWrite()) instead of the specified dwAddr parameter address. This error had no impact on any TCP/IP Stack code as these parameters always matched. However, application code using the API would have been affected. Thanks go to Marc Boon for reporting this issue on the Microchip Ethernet forum.
  2. Fixed ENC424J600/624J600 driver for PSP modes 2, 4, 6, and 10. The PIC's PMP PMMODE<9:8> bits were not set correctly.
  3. Removed from lingering references to TickGetDiff() in FTP.c, TFTPc.c and UARTConfig.c.
  4. Fixed DNS client module from returning the DNS server IP address if the DNS query failed due to a server error (i.e. DNS did respond, but did not return any records, such as when attempting to resolve a name that isn't in the DNS). DNSIsResolved() will now return 0.0.0.0 on any non-recoverable DNS error or timeout.
  5. Fixed HTTP2 MPFS upload page being accessible from URLs that weren't an exact match. For example, in 5.20 and earlier, accessing http://mchpboard/mpfsuploadASDF would still have opened the mpfsupload page. Thanks go to Andrea Rivolta on the Microchip Ethernet Forum for identifying this error.
  6. Improved UDP TX checksum code for the special case when the computed checksum was 0x0000. According to the UDP RFC, for this corner case, the checksum should be converted to 0xFFFF before transmission to differentiate from the checksum disabled case, improving error detection by a minuscule amount.
  7. Fixed GetCLKOUT() function in ENCX24J600.c driver file. Previously, 0x00 would always be returned, regardless of the value in the COCON bits of ECON2. The function documentation for SetCLKOUT() and GetCLKOUT() was also corrected (had obsolete information ported over from ENC28J60 driver file).
  8. Fixed DHCP client rebinding bug in which the DHCP client would request the wrong IP address if an unrelated DHCP OFFER or ACK message were received after we transmitted a DHCP REQUEST but before we received our DHCP ACK. Under rare conditions, this would have resulted in the TCP/IP stack reverting to the static or AutoIP assigned address for a few seconds between DHCP lease renewals.
  9. Fixed TFTP Internet Bootloader bug in which uncommon .hex files containing a certain data pattern could not be uploaded correctly to the PIC18F97J60 family device. For these problem .hex files, a block of 32 program words (64 bytes) would remain unprogrammed (left as 0xFFFF) due to a parsing error in the bootloader's DecodeHex() function. The TFTP upload operation would succeed without reporting a programming error. The problem can be detected by using an ICD3 or similar ICSP programmer and reading the program Flash out of a device that is programmed with the bootloader and application .hex files. Compare the resulting memory dump to a device programmed only with the application .hex file. If you have devices deployed in the field with the previous bootloader and happen to generate a problem application .hex file, you can potentially work around the bootloader bug by opening the application .hex file with Notepad and appending dummy address records to the beginning to move the data around in the file. For example, at the very top of the .hex file, add lines containing ":020000040000FA" until the bootload process works correctly. You may alternatively try adding spaces at the end of any line, although this may make the .hex file incompatible with some programming utilities. Thanks go to Jonathan Seidmann for identifying and reporting this bug.
  10. Fixed SNMPv2 TRAP format issue where SNMP browser was displaying all the SNMPv2 traps as SNMP version 1. SNMP v2 TRAP pdu format is rectified. Macro SNMP_STACK_USE_V2_TRAP is used to form and send a SNMPv2 TRAP PDU. SNMPTrapDemo API is used for both SNMPv1 and SNMPv2 single variable varbind trap.
  11. Fixed an HTTP2.c server module initialization bug when using the PIC32MX7XX/6XX series internal Ethernet module. During initialization the HTTPLoadConn() function would overwrite over 100 bytes of PIC RAM past the end of the reserved memory allocated for the HTTP2 module. This problem would manifest itself by locking up the TCPIP PIC32 ETH Demo App-C32 demo shortly after power up if you compiled TCP/IP Stack version 5.20 with the MPLAB C Compiler for PIC32 MCUs (C32) version 1.11.
  12. Fixed SSL client from incorrectly parsing for the server's public key in rare cases where the RSA Public Key Algorithm identifier was received, but the key hadn't been received by TCP yet. Thanks go to Kevin Maimdnet for identifing this error in SSL.c and reporting it via http://support.microchip.com/.
  13. Fixed Tick.c TickGet(), TickGetDiv256() and TickGetDiv64K() APIs sometimes returning the wrong value on PIC32 platforms. On the PIC32MX3XX/4XX family devices a wrong return result would sometimes occur if using -O3 compiler optimizations (maximum speed) with the Microchip MPLAB C Compiler for PIC32 MCUs (C32). On the PIC32MX5XX/6XX/7XX family devices, such as the PIC32MX795F512L device used on the PIC32 Ethernet Starter Kit, wrong values could be returned, regardless of the compiler optimization level.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. HI-TECH PICC-18 compilers are not supported in this release. The supplied HI-TECH PICC-18 MPLAB projects usually will not compile and/or link.
  4. LCDBlocking.c timing for the LCD_E_IO enable signal is too fast to meet published data sheet limits for various LCD controllers when compiling for a PIC32 running at > 43MHz. Despite this potential timing violation, the LCD does normally work correctly on the precompiled PIC32 demos for the Explorer 16 at 80MHz.

******

v5.20 18 November 2009

******

Changes:

  1. Added PIC32MX7XX/6XX Family integrated Ethernet controller support. The "TCPIP PIC32 ETH Demo App" folder was added to compile for the PIC32 Ethernet Starter Kit. Ethernet driver files "ETHPIC32ExtPhy.c" and "ETHPIC32IntMac.c" were added, in addition to the "ETHPIC32ExtPhyDP83848.c" file, which is a specific driver file for the National DP83848 10/100 PHY.
  2. Added RFC 3927 Auto IP module. This module will automatically assign a local IP address to the node in the 169.254.xxx.xxx private address range (subnet mask 255.255.0.0) if a DHCP server is not present on the network or the DHCP client is disable. The exact IP address chosen will be pseudo-random, but as required by the protocol, it will perform gratuatous ARPs to avoid clobbering anyone else's IP address. Also, unless there is an address collision with a preexisting node on the network, the IP address generated by the Auto IP module will not change between power cycle events (random number generator is seeded by local MAC address). To enable this module, STACK_USE_AUTO_IP must be defined in TCPIPConfig.h. When compiled in, the module defaults to enabled, but will automatically yield to the DHCP client module, which has higher priority.
  3. Added "TCPIP MDD Demo App" beta application projects. Projects in this folder store the HTTP2 web pages in external FAT16/FAT32 formatted SD card or USB Mass Storage media instead of an MPFS2 formatted EEPROM or SPI Flash. For more information on these projects, see the "Running the TCPIP MDD Demo App (Beta Release).pdf" file in the MicrochipHelp folder.
  4. Expanded XEEReadArray() API's third length parameter from a BYTE to a WORD.
  5. Converted all variable declarations and type casts of TICK data type to DWORD. The TICK typedef is now deprecated and will be removed in a future stack release. This data type conflicts with the TICK structure used in certain other Microchip software libraries.
  6. Added TCP_WINDOW_UPDATE_TIMEOUT_VAL option to the TCP.c file (default 200ms). This timeout controls the time after calling TCPGet() or TCPGetArray() before the stack will transmit a RX window update to the remote node. Historically, the TCP_AUTO_TRANSMIT_TIMEOUT_VAL value was used for this purpose (default 40ms). This change decreases the net window update transmission overhead. If this adversely affects your application RX performance (unlikely, but possible for certain communications patterns), set TCP_WINDOW_UPDATE_TIMEOUT_VAL equal to or shorter than TCP_AUTO_TRANSMIT_TIMEOUT_VAL to get the same or better behavior relative to previous stack versions.
  7. Split TCP_MAX_SEG_SIZE configuration constant in TCP.c into separate TCP_MAX_SEG_SIZE_TX and TCP_MAX_SEG_SIZE_RX configuration constants. Previously, TCP_MAX_SEG_SIZE was used to limit both the maximum size of transmit and receive packets. In cases where large TX FIFOs are allocated, and the remote node advirtises a large Maximum Segment Size TCP option, this change improves TCP transmit performance by roughly 10%.
  8. Renamed "Internet Radio App", "Internet Bootloader App" and "WiFi Iperf App" folders to "TCPIP Internet Radio App", "TCPIP Internet Bootloader App" and "TCPIP WiFi Iperf App" respectively. These new names ensure consistent folder placement when viewing the Microchip Solutions folder with other Microchip Application Libraries installed.

Fixes:

  1. Fixed SSL functionality (ex: HTTPS server) from failing when using the ENC424J600 and ENC624J600 Ethernet controllers. In stack versions 5.00 and 5.10, the BFSReg() and BFCReg() functions were being incorrectly used to set and clear CRYPTEN (EIR<15>). ENC424J600/624J600 silicon errata #6 on production silicon revision A2 prevents BFSReg() and BFCReg() from being able to modify CRYPTEN. This resulted in the SSL RSA encrypt/decrypt operations from ever finishing. The ENC424J600/624J600 errata #6 workaround is now implemented in the ToggleCRYPTEN() function in ENCX24J600.c.
  2. Fixed an RSA padding error in the ENCX24J600.c's version of RSASetData() and RSASetE() functions. This fixes the Bad Record MAC problem when using SSL client APIs with the ENC424J600 and ENC624J600, as mentioned in the 5.10 stack release notes' Known Problems section. Although unknown at the time of release this problem also occurred in stack version 5.00.
  3. Fixed DNS client from mishandling DNS responses that did not use name compression. Thanks go to Will Stone on the Microchip Ethernet forum for identifying this bug.
  4. Fixed an ExtractURLFields() API bug which would incorrectly parse the URLs containing other URLs. Ex: "http://www.google.com/search?q=http://www.microchip.com/"
  5. Fixed TickGet(), TickGetDiv256(), and TickGetDiv64K() APIs from potentially returning an incorrect time value (0x10000 ticks less than it should have) on rare occasions when using a PIC32 and with compiler optimizations turned on. The Tick.c module was also revised so that the IEC0 register does not get written to via a load-modify-store operation on PIC32s so that it is now possible for other application ISR functions to write to IEC0 without risking state corruption.
  6. Fixed PIC32 Starter Kit Debugger losing access to the PIC32 target when the project was run. JTAG was being disabled at run time, but the PIC32 Starter Kit Debugger requires JTAG to communicate with the debug executive. JTAG is now conditionally disabled on PIC32s when the __MPLAB_DEBUGGER_PIC32MXSK macro is undefined.
  7. Fixed a Berkeley sockets API bug in which calling closesocket() on a SOCK_STREAM type socket (TCP) did not actually close the socket if the remote node did not first send a FIN to the local node. This would leak a TCP socket each time the affected API calling sequence occurred and result in no FIN getting transmitted to the remote node.
  8. Fixed an HTTP2 filename parsing bug that would occur when a web browser submitted a request for a file with hex encoded characters in it. For example, with stack version 5.10 and Firefox 3.5.3, typing "http://mchpboard/%70rotect" into the URL field would have resulted in an HTTP 404 not found error when "http://mchpboard/protect/index.htm" should have been returned instead. Thanks go to Steve Tuttle for reporting this issue and suggesting a solution.
  9. Fixed a Berkeley sockets API bug in which calling recvfrom() on a datagram type socket (UDP) would return an incorrect remote IP address and port number when the from pointer was non-NULL.
  10. Fixed HTTP2 server bug in which the HTTPReadPostName() function was failing to convert the field name from URL encoding to plain-text. If the browser posted, for example, a field named "Stock Remaining", it would have been incorrectly returned from HTTPReadPostName() as "Stock+Remaining".
  11. In Stack 5.10, any new values you saved into AppConfig via the Network Configuration demo web page would have been mishandled for WiFi projects. HTTPPostConfig() in CustomHTTPApp.c of the TCPIP WiFi Demo App and TCPIP Iperf Demo App projects were corrected so that they now write a magic 0x61 marker into EEPROM/SPI Flash address 0x0000 to inidicate that the AppConfig structure is valid in EEPROM/SPI Flash. This prevents the InitAppConfig() function in MainDemo.c from restoring the default settings when changing the values through the Network Configuration page.
  12. For WiFi projects, a Gratuitous ARP Work-around was implemented to work around cases where access points send broadcast messages at data rates that the ZG2100 cannot listen to. The define USE_GRATUITOUS_ARP (in TCPIPConfig.h) turns this feature on or off.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. HI-TECH PICC-18 compilers are not supported in this release. The supplied HI-TECH PICC-18 MPLAB projects usually will not compile and/or link.
  4. ENC624J600 PSP modes 2, 4, 6, and 10 do not work at this time. Some Parallel Bit Bang modes may not work either. Some minor firmware changes are needed.
  5. TCPIP ENCX24J600 Demo App-C18.mcp project does not compile by default using MPLAB C Compiler for PIC18 MCUs (C18) version 3.34. There is not quite enough program memory available on the PIC18F97J60 for the large number of selected stack features to allow linking. To get this project to compile, turn on compiler optimizations or disable one of the modules in TCPIPConfig.h (ex: comment out STACK_USE_DYNAMICDNS_CLIENT).

******

v5.10 29 July 2009

******

Changes:

  1. Added SSL capability to the Telnet server. If STACK_USE_SSL_SERVER is defined, the Telnet server will now listen on port 992 for SSL secured connections. If you do not have a telnets client, you can use an SSL proxy, such as stunnel (http://www.stunnel.org/) to add SSL/TLS support to any telnet client.
  2. Moved a number of string pointer tables in the HTTP.c, HTTP2.c, FTP.c, and DynDNS.c files to allocate in ROM instead of RAM. This reduces around 120 bytes of RAM usage in the HTTP2 server when compiled for the PIC18 or PIC24/dsPIC platforms. The gains are even greater on PIC32 platforms.
  3. Added redefinition of SPIRAM*(), SPIFlash*(), and XEEPROM*() functions so that when compiled and used without proper HardwareProfile.h definitions, a more descript linker error will be generated instead of a mysterious symbol not found error.
  4. Added several new APIs:
    • ExtractURLFields() in Helpers.c. This function provides an easy means of parsing an URL string and extracting the protocol, hostname, port, file path, etc. Currently, this function is commented out to save code space as no stack modules require it. However, it should work correctly if you simply uncomment it (remove the #if 0...#endif around it).
    • strnchr() in Helpers.c. Finds the first occurrence of a character within a string but limited to a maximum length before giving up.
    • TCPPeek() and TCPPeekArray() in TCP.c. Reads from a TCP socket's RX FIFO buffer without removing the data from the stream.
    • TCPClose() in TCP.c. Disconnects a socket from the remote node (if connected) and closes the socket handle, including for server type sockets. This function is identical to the TCPDisconnect() API except for the handling of server sockets. TCPDisconnect() returns server sockets to the listning state and maintains the socket handle. TCPClose() closes the socket and frees all associated resources, invalidating the socket handle.
  5. Updated the DHCP client module:
    • Modified so that it wouldn't attempt to transmit DHCP Discover packets when the MAC layer reports no link (MACIsLinked() == FALSE). This avoids main() while(1) loop performance degredation when you unplug the Ethernet cable or lose association to your access point.
    • Added capability of performing DHCP discovers and requests without setting the BOOTP broadcast flag. Now, the DHCP client module will start up and attempt to obtain an IP address with the broadcast flag set, but if it fails the next DHCP retry will attempt to obtain the IP address with the broadcast flag cleared. The flag will toggle back and fourth between unicast mode and broadcast mode if no DHCP server responds. This feature improves compatibility with certain DHCP servers and WiFi access points.
    • Added several new APIs including DHCPInit(), DHCPIsEnabled(), DHCPStateChanged(), DHCPIsBound(), and DHCPIsServerDetected().
    • Removed the DHCPFlags DHCP_CLIENT_FLAGS global variable. Use the above named APIs now to get equivalent functionality.
    • Removed the DHCPBindCount global variable. To detect if the DHCP state has changed, poll the new DHCPStateChanged() function.
    • Removed the DHCPReset() API. To perform this operation, now call the DHCPInit() API. Use 0x00 for the vInterface parameter.
  6. Removed deprecated TickGetDiff() macro. To get a tick difference, just subtract the two values in-line. This macro was removed because it promoted confusing code. Ex: a-b is different from b-a. However, it was not contextually obvious which of the two was returned when TickGetDiff(a, b) was called.
  7. Added PIC32MX460F512L USB and dsPIC33FJ256GP710 PIM support to the Explorer 16 hardware profile for the TCPIP WiFi Demo App and WiFi IPerf App projects.
  8. Added all files needed for SSL (assuming the crypto libraries are present) to the TCPIP WiFi Demo App-C30 and TCPIP WiFi Demo App-C32 projects.
  9. Converted TCPIP Demo App, TCPIP WebVend App, Internet Radio App, and Internet Bootloader App MPLAB Build Directory Policy to compile in the project folder instead of the source folder. This reduces the depedancies on the MPLAB project include path and allows new projects to be created by copying one of the pre-existing folders (ex: copy "TCPIP Demo App" to "My App") without having problems including the wrong HardwareProfile.h and TCPIPConfig.h files.
  10. Changed EEPROM/SPI Flash AppConfig record valid flag from 0x60 to 0x61 in the TCPIP WiFi Demo App and WiFi Iperf App projects. This will force the various EEPROM settings to get erased when switching between Ethernet and WiFi projects. This is done since the AppConfig structure changes when using WiFi (SSID string is added).
  11. The Wifi Iperf App and TCPIP WiFi Demo App projects have been optimized for better performance.

Fixes:

  1. Fixed a TCPDisconnect() API bug in which the last few bytes of data (up to the TCP socket's TX FIFO size less 532 bytes) was not transmitted and no FIN was sent out if the TX FIFO was full of data when TCPDisconnect() was called. This problem could have only occurred for TCP sockets with a large TX FIFO (>=532 bytes). This problem could have been observed in stack version 5.00's "TCPIP Demo App-C32 EXPLORER_16 32MX360F512L ENC624J600 PSP 9.hex" precompiled application, among others, if you connected to the TCPPerformanceTest.c module and then attempted to simultaneously access the web server. The web server was returning data very slowly and failing to send the last parts of each file requested by the browser.
  2. Eliminted a potential buffer overflow vulnerability from the HTTPHeaderParseContentLength() function in HTTP2.c. If an oversized or malformed Content-Length header is sent from the web client, the function will now gracefully fail by returning an HTTP 400 Bad Request error page. Thanks go to Mark Philipp for identifying this error and suggesting a solution.
  3. Fixed a TCPOpen() problem in which the stack would continuously flood the network with nearly back-to-back ARP query packets if a client socket was created that specified a non-reachable remote IP address (ex: local gateway was offline, or for destinations on the same subnet, the actual remote node was offline). This problem would occur only after a few minutes (<10) had passed since the PIC was last reset. Thanks go to Sergey of DPS TELECOM for reporting this problem.
  4. Fixed linking problem with BigInt_helpers.S (PIC24/dsPIC only) when targeting a PIC with more than 8KB of RAM. The interface registers (_iA, _xA, _iB, _xB, _iR, and _wC) are now forced into near RAM.
  5. Cleaned up some uninitialized variable warnings in SNMP.c.
  6. Fixed a sequence variable traversal bug in SNMP.c.
  7. Cleaned up a large number of unsigned integer to signed integer comparison warnings produced by the MPLAB C Compiler for PIC18 MCUs (C18) version 3.32. With earlier versions of this compiler, these warnings would only be generated as messages, so they did not get displayed by default.
  8. Some ENCX24J600 parallel bit bang modes work now. PSP Mode 5 indirect has been tested.
  9. SSL client and server capabilities now work when using the ZeroG ZG2100M WiFi interface. In the 5.00 stack release, attempting to enable the STACK_USE_SSL_CLIENT or STACK_USE_SSL_SERVER TCPIPConfig.h options with this network controller would have resulted in an error trap. If an LCD was present, the LCD would display “encRdPtrRAWId = encWrPtrRAWId” when the error occurred.
  10. The WiFi Iperf App demo locked up when an invalid command was entered at the serial port console. This is now fixed.
  11. The WiFi Iperf App demo locked up when running with a PIC32 if iwconfig was typed at the serial port console. This is now fixed.
  12. The Wifi Iperf App demo, when running on the PIC24 and PIC32, and compiled with the –Os option (min code size optimization), did not work. This is now fixed.
  13. Change a lot of BerkeleyAPI.c internals. This may fix a number of BSD API problems.
  14. Fix a problem with SNMP variables being inaccessible with certain unique PEN numbers.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. HI-TECH PICC-18 compilers are not supported in this release. The supplied HI-TECH PICC-18 MPLAB projects usually will not compile and/or link.
  4. ENC624J600 PSP modes 2, 4, 6, and 10 do not work at this time. Some Parallel Bit Bang modes may not work either. Some minor firmware changes are needed.
  5. SSL client code doesn't work with ENC424J600/624J600 devices. The remote server terminates the connection reporting a bad record MAC (Message Authentication Code). The SSL client does work with other controllers.

******

v5.00 27 April 2009

******

Changes:

  1. Added ZeroG ZG2100 802.11 WiFi controller support. The new TCPIP WiFi Demo App and WiFi Iperf App projects have been added, which default to using this controller.
  2. Added Microchip ENC424J600/624J600 10/100 Ethernet controller support. Support for this controller is provided by the new ENCX24J600.c/.h files which perform the same role as the ENC28J60.c/.h or ETH97J60.c/.h files. Precompiled .hex files for the ENC624J600 controller require the use of the new Fast 100Mbps Ethernet PICtail Plus daughter card (AC164132). This product is not available at the time of the 5.00 TCP/IP stack release. However, it is anticipated to be available for purchase on www.microchipdirect.com in CQ3 2009.
  3. Significantly updated the Internet Radio App project. Previously, radio stations were hard coded into program memory at compile time. Now, a dynamic Shoutcast directory client has been implemented which allows retrieval of radio stations at run time, offering endless stations you can tune into. The web pages for the radio have also been updated to allow control and status reporting of the board from a web browser.
  4. Update SNMP Server (Agent) module to support SNMPv2C. The default Demo App web pages now include an SNMP reconfiguration capability to set the read and write community strings.
  5. Added ICMPSendPingToHost() and ICMPSendPingToHostROM() APIs to ICMP (ping) client module. These two APIs are available only when STACK_USE_ICMP_CLIENT and STACK_USE_DNS is defined in TCPIPConfig.h. These functions allow pinging of DNS hostnames directly without the need for the application to convert the hostname to an IP address first by manually calling the DNS client APIs. With this addition, the PingDemo.c file was updated to ping the hostname "ww1.microchip.com" instead of a static IP address. Previously, the PingDemo would stop working a couple of months after the stack was released, due to the IP address of the www.microchip.com server dynamically changing. If the DNS module is not enabled, the ping demo will instead ping the local gateway IP address instead of ww1.microchip.com.
  6. Updated TCPPerformanceTest.c code. The previous version would generate incorrect speed calculations at high data rates (ex: >1Mbyte/sec).
  7. Added multiple connection support to Telnet server example module. To allow multiple connections, define MAX_SIMULTANEOUS_CONNECTIONS in Telnet.c greater than 1 and create an equal number of TCP_PURPOSE_TELNET type TCP sockets in the TCPSocketInitializer[] definition in TCPIPConfig.h.
  8. Added more randomness to the local port selection when opening a client-mode TCP socket. This reduces the risk of reusing a previously used port number if the user power cycles the device.
  9. Updated XEE* SPI EEPROM API functions. Writes are no longer required to start on an EEPROM page boundary, and writes can now be arbitrarily long without having to call XEEEndWrite() at each page boundary. Additionally, the XEEWriteArray() API has been added, which performs a similar operation to the SPIFlashWriteArray() API (but with no special erase cases to worry about).
  10. Decoupled AppConfig storage in external SPI EEPROM or SPI Flash option from MPFS_USE_EEPROM and MPFS_USE_SPI_FLASH options. MainDemo.c will now save the AppConfig structure in external non-volatile memory, even if MPFS is unused (no HTTP or SNMP server modules enabled) or MPFS is using internal Flash program memory to store web pages/bib information. This change also allows the XEE*() and SPIFlash*() non-volatile read/write functions to be available at all times (even if MPFS is unused), as long as the appropriate hardware pinout definitions are present in HardwareProfile.h. SPI Flash and SPI EEPROM are no longer mutually exclusive with each other. However, if both are enabled simultaneously, AppConfig will be stored in the EEPROM, not the SPI Flash.
  11. Added required SSL files to TCPIP Demo App MPLAB projects. SSL capabilities can now be turned on directly via the STACK_USE_SSL_SERVER and STACK_USE_SSL_CLIENT options in TCPIPConfig.h for these projects, assuming appropriate crypto libraries are installed (SW300052 available from https://www.microchipdirect.com/). With this change, the historical "SSL Demo App" folder has been removed.
  13. Updated HardwareProfile.h files. This includes the addition of PIC18 Explorer board support, removal of the PICDEM Z profile, changes to the HI-TECH PICC-18 profiles for newer compilers, among other changes.
  14. Added a TCP and UDP performance test measurements table to TCPIP Stack Help (TCPIP Stack Help.chm). Access this from the "Microchip TCP/IP Stack" book, "Stack Performance" page.
  15. Updated MPFSlib project (Microchip.MPFS.dll file) so that C18 and C32 output from the MPFS2.exe utility is now identical for MPFS2 images. The generated .c file is now compatible with both C18 and C32 compilers simultaneously. Previously, the images generated for C18 would compile successfully for C32 projects, but would potentially operate incorrectly when compiler optimizations were turned on. Images generated for C32 would compile successfully and work on C18 projects, but the C18 compiler would take a very long time to process the file each time you rebuilt your MPLAB project. Now, the image generated for C18 matches the image generated for C32 and it will compile fast and work correctly on both platforms, even with compiler optimizations turned on.
  16. Added schematics and BOMs for the Ethernet PICtail, Ethernet PICtail Plus, Fast 100Mbps Ethernet PICtail Plus, Internet Radio, PICDEM.net 2, and ZeroG ZG2100M PICtail development boards to the "MicrochipTCPIP StackDemo Board Files" folder.

Fixes:

  1. Fixed a denial of service vulnerability in the NBNSGetName() function of the NBNS.c file. Previously, if a deliberately malformed packet was received, the PIC RAM could have become corrupted. Thanks go to David Talmage for finding this vulnerability.
  2. Fixed Timer1 interrupt flag clearing code on PIC32 products. Previously, the Tick.c module was clearing the interrupt flag in an unsafe manner which could have corrupted other interrupt flags in the IFS0 register. Thanks go to Leon van Snippenberg working on the AVIX-RT RTOS for pointing this error out on the Microchip forums.
  3. Fixed SNMP up-time variable. Previously the CustomSNMPApp.c module would respond with the number of Tick API ticks that elapsed, not the number of 10ms time slices that elapsed. The SNMP standard uses 10ms as its time base.
  4. Fixed BigInt_helper.asm's _masBI() and _masBIROM() functions when the Br parameter's length modulo 4 was equal to 1 or 2. This bug previously caused the BigIntMod() function to sometimes go into an endless calculation loop on PIC18 products when using the SSL libraries and certain combinations of modulus data and length were used. Thanks go to Vasil Stoianov on the Microchip Ethernet forum for running into this defect and reporting it.
  5. Fixed SSLSessionNew() so that it wouldn't "lose" SSL sessions after waiting a few hours. This would previously make it impossible to make new SSL connections after a while, but then after a few more hours, the sessions would become free again. Thanks go to Jim Stephens for identifying this issue and finding the solution.
  6. Fixed an SSL 2.0 antique client hello record length calculation bug occurring when a received record was > 255 bytes.
  7. Added retransmission capability to SendNotification() function in CustomSNMPApp.c. Previously, if an SNMP trap were sent, but the initial ARP query or response was lost on the network, the SendNotification() code would have deadlocked, and suppressed all future transmission of SNMP traps.
  8. Fixed DNS client timeout if the DNS server is unable to be ARPed. Previously, the DNS client would retry ARPing the DNS server indefinitely if it was offline. Now, the DNS client will correctly abort if too many attempts to ARP the DNS server fail. Thanks go to Phil "andersop" on the Microchip Ethernet forum for identifying this error.
  9. Suppressed transmission of a TCP RST packet to an unknown IP or MAC address if the TCPDisconnect() function was called on a client mode socket that was not finished with ARP or DNS resolution yet. Thanks go to Phil "andersop" on the Microchip Ethernet forum for pointing this behavior out.
  10. Fixed TCP socket from disconnecting if the remote receive window was zero and TCPFlush() was still called. Thanks go to Bob Topper for identifying this issue and suggesting a solution.
  11. Fixed Tick.c module returning incorrect values when TickGet() or other API was used with compiler optimizations turned on. Wrong values were observed when using MPLAB C Compiler for PIC24 MCUs and dsPIC DSCs version 3.12.
  12. Fixed a number of SPI communications problems that could occur when compiler optimizations were turned on. The ENC28J60 was observed to not work correctly on the dsPIC33FJ256GP710 processor when compiled with MPLAB C Compiler for PIC24 MCUs and dsPIC DSCs version 3.12.
  13. Fixed possible MPFS2 error when using an ASM30 .s image where MPFS_Start would be read using the wrong PSVPAG setting. You must rebuild your MPFS2 image file (ex: MPFSImg2.s) with this stack version's MPFS2.exe utility to get this correction applied.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. HI-TECH PICC-18 compilers are not supported in this release. The supplied HI-TECH PICC-18 MPLAB projects usually will not compile and/or link.
  4. ENC624J600 PSP modes 2, 4, 6, and 10 do not work at this time. Parallel Bit Bang mode does not work either. Some minor firmware changes are needed.

******

v4.55 10 November 2008

******

SSL Note: RSA.c and ARCFOUR.c have not changed between the 4.50 and 4.55 releases. Although the precompiled SSL Demo App .hex files will differ, you can continue to use the previous TCP/IP Stack v4.50 Encryption Add-on with this 4.55 stack version.

Changes:

  1. Added DNS client support for a secondary DNS server address. Previously, the AppConfig.SecondaryDNSServer setting was unused. Now, the DNS client module will automatically swap the AppConfig.PrimaryDNSServer and AppConfig.SecondaryDNSServer values after any DNS query timeout (or ARP timeout for the DNS server) and attempt the query with the alternative server. If AppConfig.SecondaryDNSServer is disabled by setting it to the IP address 0.0.0.0, the DNS client will only use the AppConfig.PrimaryDNSServer value and never swap the values. With this change, the DHCP client was also updated. If the DHCP server does not specify a secondary DNS server, then the DHCP client will now set the AppConfig.SecondaryDNSServer value to 0.0.0.0. Previously, it would change the AppConfig.SecondaryDNSServer setting only if the remote DHCP server offered a secondary DNS server.

Fixes:

  1. Updated Internet Bootloader App project to correctly detect if the configuration bits are being changed or not. Previously, the bootloader always thought the configuration bits were being changed and thus had to always erase the last Flash page (largest memory address) twice for each firmware update. This did not cause any functional problems or specification violations, but it would decrease the effective Flash endurance of the last page.
  2. Fixed a TCP socket memory corruption bug that would occur if TCPGetRemoteInfo() API was called twice with different socket handles without an intermediate call to any other TCP API that takes a TCP_SOCKET input. Thanks go to Bob Topper for identifying this problem and suggesting a solution.
  3. Fixed the UDPIsGetReady() function so that it returns the number of bytes remaining in the packet based on the current read location. This is the same behavior as stack versions 4.18 and earlier. In stack versions 4.50 and 4.51, the UDPIsGetReady() function would always return the total number of bytes in the current packet, regardless of how many bytes the read pointer had been advanced through the UDPGet() and UDPGetArray() functions. Thanks go to Bob Topper for identifying this problem and suggesting a solution.
  4. Fixed demo admin web page in TCPIP Demo App project so that the last byte of the MAC address can be changed, independent of the format it was entered by the user.
  5. Fixed a buffer overflow bug that would occur when using the SSL server during hashing of the server certificate for the initial handshake. This error previously caused several bytes of random variables elsewhere in the project to get overwritten for each SSL connection.
  6. BSD sockets API was updated to fix some issues.
  7. LCDBlocking.c was updated to relax start up timing. This timing fix is specifically needed to support Explorer 16 boards with a Truly TSB1G7000 display (Novatek NT7603H controller).
  8. Removed four uses of Arial Black font in MPFS2.exe utility. On some rare PC configurations, the use of this font caused the executable to not run.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail.
  4. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate TCP_ETH_RAM_SIZE or MAX_HTTP_CONNECTIONS.
  5. HI-TECH PICC-18 STD 9.51PL1 cannot compile DynDNS.c. It raises an "inconsistent type" error while trying to perform a ROM pointer to integer cast. The older 9.50PL3 compiler release is required to compile this file.
  6. HI-TECH PICC-18 STD 9.50PL3 does not initialize several static variables correctly on reset. This behavior breaks many stack modules in the TCPIP Demo App and TCPIP WebVend App projects. Additionally, string printing functions do not work correctly, so the supplied "TCPIP Demo App-HITECHPICC18 PICDEMNET2 18F97J60.hex" and "TCPIP WebVend App-HITECHPICC18 PICDEMNET2 18F97J60.hex" files may not correctly print the board's DHCP assigned IP address on the board's LCD (if present) and UART. To avoid these severe problems, use the Microchip MPLAB C Compiler for PIC18 MCUs. A free student edition can be downloaded from http://www.microchip.com/c18.

******

v4.51 24 July 2008

******

IMPORTANT NOTE: You must use MPLAB 8.10 or higher to successfully open the MPLAB projects.

SSL Note: RSA.c and ARCFOUR.c have not changed between the 4.50 and 4.51 releases. Although the precompiled SSL Demo App .hex files will differ, you can continue to use the previous TCP/IP Stack v4.50 Encryption Add-on with this 4.51 stack version.

Changes: None. This release includes bug fixes only. It is very important that applications using the ENC28J60 get fix item 7, below.

Fixes:

  1. TCPOpen() was previously failing if you used it to start a connection with a remote hostname, but the DNS module failed to resolve the remote address on the first try. This, for example, would occur if you powered up your board and tried to connect to a remote server before the Ethernet cable was attached. Once the Ethernet cable was attached, the socket would attempt to resolve and connect to a garbage address. The Internet Radio application would sometimes not begin playing the default station upon power up because of this problem.
  2. Set SEQ.ACK = 0 for outbound TCP SYN packets. This fixes a connection compatibility problem with certain paranoid TCP/IP stacks that would validate this field even though the ACK flag was clear. This problem would previously cause the Microchip TCP/IP stack to be unable to connect client-mode TCP sockets to certain rare servers/services. Thanks go to Jean LE TUTOUR for finding one of these problem servers.
  3. MPFSOpen() and MPFSOpenROM() for MPFS2 could leak a file handle if a name hash matched but no complete file name did. This has been corrected to prevent potential DOS attacks on the HTTP2 web server. Thanks to David Tan on the Microchip Ethernet formus for identifying this issue.
  4. Fixed a bug in MPFS2.1 that caused compile errors when MPFS Classic images were generated for ASM30 containing files whose length was either zero or a multiple of 12.
  5. Fixed an issue in HTTPPostConfig() that caused it to ignore the flag that was set when invalid IP address input was detected. This issue only affects the example configuration page and only exists in v4.50 (prior versions functioned correctly). Also corrected an issue where user input could potentially overflow into part of the shadow AppConfig in the same function. Thanks to prinz3nroll3 on the Microchip Ethernet forums for identifying both of these issues.
  6. Implemented Explorer 16 development board 5V LCD errata workaround to LCDBlocking.c. This corrects the A/D converter from returning erratic readings on certain Explorer 16 boards. LCD I/O pins are now continuously driven by the microcontroller instead of going high impedance when idle.
  7. Fixed a critical ENC28J60 revision B7 errata workaround problem in the ENC28J60.c, MACFlush() function. Previously, the code was checking for an EREVID register value of 0x07 for silicon revision B7. This was incorrect. Silicon revision B7 actually has an EREVID value of 0x06. Note that this problem was caused by an incorrect EREVID value published in DS80349A, the B7 silicon errata documentation. Make sure to use DS80349B or later.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail.
  4. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate TCP_ETH_RAM_SIZE or MAX_HTTP_CONNECTIONS.
  5. HI-TECH PICC-18 STD 9.51PL1 cannot compile DynDNS.c. It raises an "inconsistent type" error while trying to perform a ROM pointer to integer cast. The older 9.50PL3 compiler release is required to compile this file.
  6. HI-TECH PICC-18 STD 9.50PL3 does not initialize several static variables correctly on reset. This behavior breaks many stack modules in the TCPIP Demo App and TCPIP WebVend App projects. Additionally, string printing functions do not work correctly, so the supplied "TCPIP Demo App-HITECHPICC18 PICDEMNET2 18F97J60.hex" and "TCPIP WebVend App-HITECHPICC18 PICDEMNET2 18F97J60.hex" files may not correctly print the board's DHCP assigned IP address on the board's LCD (if present) and UART. To avoid these severe problems, use the Microchip MPLAB C Compiler for PIC18 MCUs. A free student edition can be downloaded from http://www.microchip.com/c18.

******

v4.50 02 June 2008

******

IMPORTANT NOTE: You must use MPLAB 8.10 or higher to successfully open the MPLAB projects. Also, ensure that the latest C compiler is used. This release was tested against MPLAB C Compiler for PIC18 MCUs version 3.20, MPLAB C Compiler for PIC24 MCUs and dsPIC DSCs version 3.10, MPLAB C Compiler for PIC32 MCUs version 1.01, and HI-TECH PICC-18 version 9.50PL3 (STD). Earlier compilers may not be able to compile this TCP/IP stack release.

Changes:

  1. Added SSL 3.0 client capabilities, including SMTP over SSL. The SSL modules supports up to 1024-bit RSA handshakes and 128-bit ARCFOUR bulk encryption. This can be demonstrated using the SMTP client. SSL server support is functional, but a key generation utility is not yet provided and support over HTTPS is not yet reliable with all browsers. IMPORTANT: Encryption software is covered by US Export Control law, so it is not directly downloadable from the Microchip website. To use the encryption modules, you must order SW300052 from microchipDIRECT [ https://www.microchipdirect.com/ ] and install the required libraries.
  2. Added Berkeley Sockets Distribution (BSD) API translation layer. You can now call the well know Berkeley APIs instead of or in addition to the Microchip specific APIs. To use this new functionality, define STACK_USE_BERKELEY_API and configure BSD_SOCKET_COUNT in TCPIPConfig.h. Three new source code demos are provided to demonstrate this API: BerkeleyTCPClientDemo.c, BerkeleyTCPServerDemo.c, and BerkeleyUDPClientDemo.c. The TCP client demo is identical to the GenericTCPClient.c demo, but implemented using Berkeley Sockets. The UDP client demo is similarly identical to the SNTP.c client. The TCP server demo listens on TCP port 9764 and will echo any traffic received back to the sender. It allows up to 3 simultaneous connections when there are an adequate number of sockets defined in the TCPSocketInitializer[] array in TCPIPConfig.h.
  3. Added support for Dynamic DNS services. See the Dynamic DNS Client module in the TCP/IP Stack Help for details. Presently, dyndns.org, dyndns.com, no-ip.com, and dns-o-matic.com are supported.
  4. Added the Microchip TCP/IP Configuration Wizard to the Utilities folder, facilitating easier configuration of the TCP/IP Stack through a graphical application.
  5. Restructured TCPIPConfig.h to remove rule-enforcement logic, placing the removed sections in TCPIP.h. Many other project structure changes were also made to clean up the general distribution appearance.
  6. Increased DHCP Server default lease duration to 60 seconds instead of 15 seconds. Some computers were losing their IP lease before performing a renew operation with only a 15 second lease.
  7. Removed CLOCK_FREQ, INSTR_FREQ, and PERIPHERAL_FREQ macro definitions. GetSystemClock(), GetInstructionClock(), and GetPeripheralClock() now return these respective values. This change was made for compatibility with other Microchip software libraries.
  8. Added TCP Fast Retransmission capability. Whenever three duplicate ACK packets arrive, the stack will now immediately perform a retransmit operation. This greatly improves recovery latency whenever the network loses a packet for applications that stream TX data using TCP.
  9. Improved TCP Keep Alive mechanism to automatically close TCP sockets which do not receive any keep-alive responses for TCP_MAX_UNACKED_KEEP_ALIVES (default 6) times. This means that, by default, any connection that catastrophically breaks without notifying us (ex: user unplugs cable, Internet connection goes down, etc.) will time out and automatically close after 60 seconds (TCP_MAX_UNACKED_KEEP_ALIVES * TCP_KEEP_ALIVE_TIMEOUT). Server oriented sockets will return to the listening state. Client oriented sockets will close, but the TCP_SOCKET handle will continue to remain valid until the application calls TCPDisconnect(). Applications can check if the socket became disconnected and reset by calling TCPWasReset() or TCPIsConnected(). Note that this keep alive implementation will only close sockets that are broken (remote node is not responding to TCP requests). It will not close or otherwise interfere with idle connections in which the application is not transmitting or receiving data and wishes to keep the connection open.

10.Added a TCP RX SYN queue of depth TCP_SYN_QUEUE_MAX_ENTRIES (default 3). This queue automatically saves incoming SYN packets destined for a local server port which is already connected to a different client. When the client disconnects, the SYN data is pulled out of the queue and the socket immediately attempts to connect to the next client. This improves connect time performance since the remote client no longer has to retransmit the SYN request if it was unserviceable the first time around. This is most apparent with the HTTP/HTTP2 servers which previously performed poorly with certain modern web browsers which attempt to open many simultaneous connections to the web server, such as Mozilla Firefox 3 beta 5 and Apple Safari 3.1. Entries in the queue automatically time out after TCP_SYN_QUEUE_TIMEOUT (default 3 seconds) so as to prevent the queue from filling up permanently if several connection requests arrive for a service that is in use and will not be available for an extended period. 11.Modified the structure of the MPFS2 FAT (now known as MPFS2.1) to include name hashes first. This speeds up opening files by 25%, and makes opening index files nearly instant. 12.Updated the MPFS2 Utility. MPFS2.1 now supports the new FAT structure and provides a cleaner interface. It also writes images to disk as they are created, which eliminates the IndexOutOfBounds exceptions some users had reported. Finally, uploads are now truly multi-threaded. 13.Source code to the MPFS2.exe PC utility is now released. Find it in the Microchip SolutionsMicrochipTCPIP StackUtilitiesSourceMPFS21 folder. This project is designed to compile with Microsoft Visual C# 2008 Express Edition. 14.Added support for SST25VFxxxB serial flash parts in 2, 4, 8, 16, and 32Mbit densities. These parts can be used to replace EEPROMs for storing MPFS images (both versions) and custom data. 15.Added HTTPReadPostName, HTTPReadPostValue, and HTTPReadPostPair functions to facilitate easier processing of data arriving via POST. 16.Split HTTPAuthenticate API into separate functions: HTTPNeedsAuth and HTTPCheckAuth. This function was already split internally, and didn't make sense as a single API. 17.Updated DHCP client to close its UDP socket when idle (bound state) to save a small amount of resources. 18.Removed LED_IO macro from all hardware profiles because it is not suitable for use on certain hardware platforms that have non-contiguous LEDs or reversed bit ordering. Use the new LED_GET() and LED_PUT(val) macros to read and write to all of the LEDs at once. 19.Added Ethernet Hash Table Calculator.exe to the Utilities folder and start menu. This tool will calculate the correct bit that you must set in the EHT0-EHT7 registers on the ENC28J60 and PIC18F97J60 family devices for using the Hash Table RX filter. This is useful only for fixed MAC addresses known at design time. For addresses that are known at run time, use the SetRXHashTableEntry() function in the ENC28J60.c or ETH97J60.c files to set the correct EHT0-EHT7 bit.

Fixes:

  1. Fixed a buffer overflow data corruption issue in the FTP module that arises when too many parameters were passed on the command line.
  2. Moved TCPWasReset checking in HTTP2 to execute for every socket on every loop. Previously, it would only execute when a socket reconnected, which caused the RX buffer to not resize until after data was received. Some platforms (notably FF2 on Ubuntu) would stall if the initial advertised RX window was too small, and this change corrects that issue.
  3. Updated SendSystemReset() and MACInit() initialization routine in ENC28J60.c. Previously, if the ENC28J60 was placed into sleep mode by calling MACPowerDown(), the SendSystemReset() command would not work anymore. This would leave the ENC28J60 in power down if the host PIC was ever reset. SendSystemReset() should work for all conditions with this update. Thanks go to Rob Haverkort on the Microchip Ethernet forum for identifying this problem.
  4. Fixed an alignment bug in HTTP2 that caused redirects to fail when the MPFS2 image was stored in Flash program memory. Thanks to Todd Boaz on the Microchip Ethernet forum for identifying this bug, and Chen Qu for posting a solution.
  5. Fixed SNTP client from losing accuracy if you called SNTPGetUTCSeconds() 10s of thousands of times since the last server synchronization. Thanks go to "pic123" on the Microchip Ethernet forum for noticing this error.
  6. Fixed a TickGet*() API problem where the returned tick value could be off by 64K ticks occasionally on PIC24, dsPIC30/33, and PIC32 processors. This bug was previously fixed in stack versions 4.13 and 4.16, but it was unintentionally recreated in 4.18 due to PIC32 changes.
  7. Fixed UART2TCPBridge module from failing to connect to a remote server when USE_REMOTE_TCP_SERVER was defined.
  8. Fixed an issue that prevented SNMP SETs on 16 and 32 bit parts when using MPFS2. Thanks go to Milena K on the Microchip Ethernet forum for identifying this problem.
  9. Fixed a rare buffer corruption issue that could occur with UDP if TCP was also enabled.

10.Fixed a Tick rollover error in HTTP2. Thanks go to Paul Bixel on the Microchip Ethernet forum for identifying this problem. 11.Fixed an MPFS2 bug in which an excessive value to MPFS_SEEK_REWIND may have failed to return an error. Thanks go to Paul Bixel on the Microchip Ethernet forum for identifying this problem as well. 12.SMTP Client now sends EHLO when using authentication. Previously, the HELO command was used, even with authentication enabled. Using HELO with authentication creates incompatibilities with certain SMTP servers. 13.Improved Internet Bootloader robustness by retransmitting ACKs in response to data retransmissions by the remote sending node. Previously, if an ACK packet was lost before reaching the sending node, the TFTP upload would fail and need to be restarted. Thanks go to "coolvibe" Dave Collier on the Microchip Ethernet forum for identifying this behavior. 14.Fixed TFTP Internet Bootloader from not being accessible from Linux TFTP clients which were setting the IP header "Don't Fragment" flag bit. 15.Changed TCP so that unsent data that is automatically flushed by the TCP_AUTO_TRANSMIT_TIMEOUT_VAL timer includes the PSH flag. This improves GUI responsiveness for certain applications which rely on this automatic flush feature, such as the UART2TCPBridge module. 16.Fixed TCP socket loss issue which could occur if the TCP TX FIFO size was greater than 536 bytes (TCP_MAX_SEG_SIZE). Before the fix, the socket would have gotten tied up indefinitely performing retransmissions every 1.0 seconds without detecting that the remote node was disconnected. 17.Fixed TCP socket hang issue that would occur if the PIC sent out a FIN and the remote node never responded with a corresponding FIN. The socket would have gotten stuck indefinitely in the TCP_FIN_WAIT_2 state. Thanks go to Mr. Kyle Strickland with AW North Carolina for identifying this bug. 18.Fixed UDPSetRxBuffer() function from not working if it was called before having called UDPGet() or UDPGetArray() at least once. 19.Fixed an offset error of +2 milliseconds being returned from TickConvertToMilliseconds(). Thanks go to Andrés ("saturn") on the Microchip Ethernet forum for finding this error. Note that due to integer truncation during division, this function can be off by 0.2% or so, depending on the value returned by GetPeripheralClock(). 20.Updated DelayMs() macro for MPLAB C Compiler for PIC18s to work correctly when a large parameter was given. You should now be able to delay between 0 and 65535 milliseconds across all supported compilers without ending up with an unexpectedly short delay.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail.
  4. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate TCP_ETH_RAM_SIZE or MAX_HTTP_CONNECTIONS.
  5. HI-TECH PICC-18 STD 9.51PL1 cannot compile DynDNS.c. It raises an "inconsistent type" error while trying to perform a ROM pointer to integer cast. The older 9.50PL3 compiler release is required to compile this file.
  6. HI-TECH PICC-18 STD 9.50PL3 does not initialize several static variables correctly on reset. This behavior breaks many stack modules in the TCPIP Demo App and TCPIP WebVend App projects. Additionally, string printing functions do not work correctly, so the supplied "TCPIP Demo App-HITECHPICC18 PICDEMNET2 18F97J60.hex" and "TCPIP WebVend App-HITECHPICC18 PICDEMNET2 18F97J60.hex" files may not correctly print the board's DHCP assigned IP address on the board's LCD (if present) and UART. To avoid these severe problems, use the Microchip MPLAB C Compiler for PIC18 MCUs. A free student edition can be downloaded from http://www.microchip.com/c18.

******

v4.18 28 November 2007

******

Changes:

  1. Added C32 and PIC32MX support. Some things were cleaned up in the process.
  2. Removed linker scripts from C30 MPLAB projects. MPLAB IDE 8.00 can automatically select the correct linker script for 16-bit and 32-bit products.
  3. Updated TCPPerformanceTest.c module. Now it automatically calculates the TX throughput and displays it for you. Also, there is now an RX throughput testing mode, which listens on a separate TCP socket (port 9763) when a TCP socket of type TCP_PURPOSE_TCP_PERFORMANCE_RX is allocated in TCPIPConfig.h. The RX socket is by default not enabled to save memory, so you must create a TCP_PURPOSE_TCP_PERFORMANCE_RX socket in TCPIPConfig.h and ensure that enough memory is allocated to accommodate it to test the RX performance test. When connected to port 9763, send a large amount of data and the PIC microcontroller will send back a count of how many bytes were received per second.
  4. UDPPerformanceTest.c module now transmits 1024 packets on start up and then stops to prevent continually broadcast flooding your network. To transmit more packets after 1024 is reached, hold down BUTTON3 (left-most button on most boards).
  5. Significantly improved the speed of the MD5 and SHA-1 functions. Gains for the 8-bit compilers were 50-75%, while 16-bit parts saw more modest improvements (~10%).
  6. Reimplemented TCP_CLOSE_WAIT TCP state ("CLOSE WAIT" in RFC793). Now, TCP sockets that receive a FIN from the remote node will hold off transmitting a FIN back to the remote node until the TCP_CLOSE_WAIT_TIMEOUT (defined at the top of TCP.c) elapses or immediately when the application calls the TCPDisconnect() function. This makes it possible for the application to transmit a response back to the remote node before the socket becomes closed on our end. Similarly, it simplifies application usage of the last RX bytes received as these bytes are now assured to still be in the RX FIFO for at least TCP_CLOSE_WAIT_TIMEOUT seconds. TCP_CLOSE_WAIT_TIMEOUT defaults to 200ms in this stack version.
  7. Pushed the SNTP requery on failure timeout up some. It was ~14 seconds and is now ~20 seconds.
  8. Added TFTPOpenROMFile() API to complement TFTPOpenFile() when using PIC18 products.
  9. Added a fourth parameter to newAJAXCommand() in mchp.js, allowing data to be POSTed along with the AJAX request.

10.Deprecated the TCP Loopback functions, which includes TCPOpenLoopback, TCPCloseLoopback, TCPIsLoopback, TCPInject, and TCPSteal. These functions were added in 4.10 for future SSL support, but have since become unnecessary. They are of limited usefulness, and so are being removed to save code space. The functions are still available in this version, but will be removed in the next release. 11.Added SMTPClient.ServerPort field to the SMTP API. This allows the remote server port number to be specified dynamically at run time instead of being hard coded to the SMTP_PORT value defined at the top of SMTP.c. SMTP_PORT is now only a default. 12.Added web interface to the SMTP module in the TCPIP Demo App applications. You can now configure the SMTP module and send emails directly from within your web browser. The HTTPPostEmail() function in CustomHTTPApp.c also demonstrates how to send MIME encoded attachments in emails. The default demo will send button states, LED states, and the current potentiometer reading as a CSV file attached to the email. 13.Changed SMTPDemo() in MainDemo.c to trigger on BUTTON2 and BUTTON3 simultaneously held down instead of BUTTON0 only.

Fixes:

  1. Fixed an ENC28J60.c MACGetArray() bug which would overwrite one byte of memory at address 0xFFFFFFFF if you provided NULL for the destination address pointer.
  2. Fixed an MPFS2.c MPFSGet() bug which would overwrite memory address 0x00000000 if a NULL pointer was provided as the destination.
  3. Fixed a bug in the HTTP2 server accessing incorrect sockets if an inadequate number of sockets were available on POR.
  4. Fixed Internet Bootloader project from failing with a timeout if an ARP packet arrived during the Erase/Write operation.
  5. Fixed DHCP client RFC non-compliance where it would send the ciaddr field in the initial SELECTING state. Also, in the RENEWING state, the Requested IP Address option was being sent, which is illegal. These changes may fix compatibility problems with certain DHCP servers.
  6. Fixed TFTP Client's TFTPCloseFile() function from sending data using a wrong UDP socket if StackTsk() was called after TFTPIsFileOpened() was last called.
  7. Added two zero bytes to the ICMP echo request payload to improve compatibility with some buggy NAT routers.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  3. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail.
  4. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate TCP_ETH_RAM_SIZE or MAX_HTTP_CONNECTIONS.

******

v4.16 06 November 2007

******

Changes:

  1. Added Internet Radio application. This is a TCP client application which downloads streaming MP3 audio from a Shoutcast server and then plays it back to stereo earphones via a VLSI VS1011 audio decoder.
  2. Added SPIRAM.c module. This module is intended for interfacing to an AMI Semiconductor N256S0830HDA SPI RAM chip. The TCP module can now interface directly to this SPIRAM module to store TCP socket FIFO buffers and other TCB data in the external RAM.
  3. Added TCP_OPTIMIZE_FOR_SIZE compile time configuration macro to TCP.c file. When optimizing for small code size, the TCP module ROM footprint shrinks up to 6KB, but performance may slow down on some processors (namely PIC18s, where the penalty is approximately 15%).
  4. Added USE_EEPROM_25LC1024 compile time configuration macro to TCPIPConfig.h. Enable this definition if you are storing your MPFS[2] on a 1Mbit 25LC1024 or similar EEPROM device that uses 24-bit addressing and a 256 byte write page size.
  5. Changed LCDBlocking.c module initialization code. It should now be possible to use 4-bit mode on certain "unusual" LCD controllers, like the Samsung S6A0032. Most PICDEM.net 2 and Explorer 16 boards use an LCD with this controller.
  6. SNTP client now attempts to requery the SNTP server about every 14 seconds if the last query attempt fails. This allows the internal time value to become valid quickly should the board be powered up before an Ethernet cable is attached or if the DHCP client doesn't obtain an IP address quickly enough. Previously, it would take up to 10 minutes after plugging the Ethernet cable in to get a correct time value from the SNTP server.
  7. Added UDP_USE_TX_CHECKSUM compile time configuration macro to TCPIPConfig.h. When enabled, all UDP packets will have a correct UDP checksum computed and inserted into the UDP header of outbound packets. If you do not define this macro, the UDP checksum will be disabled (left as 0x0000), which is how previous stack versions operated. Note that enabling checksum generation cuts your maximum UDP TX throughput by nearly half due to the required computations.
  8. Substantially changed TCP socket RX and TX FIFO allocation. Now, sockets can be stored either in Ethernet RAM, PIC RAM, or external (SPI) RAM. Previously, sockets could only be allocated in Ethernet RAM, which was not scalable.
  9. Added TCPOpen() API function. This replaces TCPListen() and TCPConnect(). TCPOpen() supports a large number of options that will make the creation of client mode sockets much easier. You can specify the remote node as a hostname that needs DNS and ARP resolution, an IP address that only needs ARP resolution, or legacy NODE_INFO pointer for direct compatibility with the previous TCPListen() and TCPConnect() APIs. TCPOpen() also supports a socket type parameter which will allow you to use the new TCP socket RAM allocation system.

10.Added TCP Keep Alive mechanism defined by RFC 1122 section 4.2.3.6 to the TCP module. This helps automatically detect lost connections. If the remote node sends back an RST, this immediately closes the lost connection on our end. Currently, no action is taken if the keep alive gets no response. Note that this feature deviates from the standard by defaulting to only 10 seconds instead of over 2 hours. Also deviating from the standard, this feature is enabled by default. To disable it, undefine TCP_KEEP_ALIVE_TIMEOUT at the top of TCP.c. 11.Moved TCPPerformanceTest.c module from default port 12345 to 9762. 12.Moved UDPPerformanceTest.c module from default port 12345 to 9, the "discard" protocol port.

Fixes:

  1. The DHCP client now specifically requests the previous IP address when a DHCP renewal occurs.
  2. The SNTP client now correctly maintains time when repetitively calling SNTPGetUTCSeconds() between an NTP requery event. Thanks go to Rob Haverkort on the Microchip Ethernet forum for noticing the time value incrementing far faster than it should have.
  3. TCP module will not transmit a bunch of unnecessary duplicate ACK packets when data is ready to be transmitted but the remote RX window is zero. This previously didn't cause anything to break, but would waste CPU time and bandwidth sometimes.
  4. TCP sockets will no longer automatically close if the remote RX window stays zero for several seconds.
  5. Fixed TFTP Internet Bootloader project from corrupting the configuration fuses. Previously, this would result in the Watchdog timer being enabled and causing an unintentional reboot every few minutes with the demo TCP/IP stack.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. TFTPc module has not been tested with this version.
  3. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  4. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail.
  5. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate MAX_TCP_SOCKETS, TCP_TX_FIFO_SIZE, TCP_RX_FIFO_SIZE, or MAX_HTTP_CONNECTIONS.

******

v4.13 02 October 2007

******

Changes:

  1. Added command line support to the MPFS2.exe tool. You can now generate MPFS output files using batch scripts or other console applications.
  2. Added dynamic variable parameter capabilities to the MPFS2 utility. To use, add the parameters you wish to pass to the end of the dynamic variable. All parameters are passed as WORD values. (ex: ~myArray(2,5)~ )
  3. Added TCPWasReset() API to allow the application layer to be notified if an underlying socket reset has occurred (ex: remote node disconnects, cable is disconnected and times out, user calls TCPDisconnect(), etc.). The reset state is latching, which allows the application layer to detect if a remote node disconnects and a new connection occurs on the same socket before the application can detect the original disconnection through the TCPIsConnected() API.
  4. Added a counter to the UDPPerformanceTest module and made it supress transmission if an Ethernet link is not present.
  5. Added TCPIP WebVend App example application to the main stack distribution. This corresponds to three new Microchip Webinars being published on the HTTP2 server usage topic.

Fixes:

  1. Fixed MPFS2.exe PC utility from crashing if you attempt to generate an MPFS classic .bin/.c/.s output file.
  2. Fixed RCONbits definition for HPC_EXPLORER hardware profile when using the HI TECH PICC-18 compiler.
  3. Fixed a MPFSGetFilename() bug when using C30 and MPFS2 images stored in program memory. Thanks to Billy Walton on the Microchip Ethernet forum for identifying this issue.
  4. Fixed a TCP RX FIFO corruption problem which would occur if the remote node sent more data than could fit in our RX FIFO in a single packet. The GeneticTCPClient.c module was subject to experiencing this problem when connected to www.google.com's servers.
  5. Fixed a DHCP client UDP socket leak if you called DHCPDisable() after the DHCP client had already obtained a UDP socket. Thanks go to Matthew Kendall on the Microchip Ethernet forum for identifying this problem.
  6. Fixed a SNMP Server module bug testing a string length (with respect to SNMP_COMMUNITY_MAX_LEN) being off by one, resulting in possible memory corruption. Thanks go to Matthew Kendall on the Microchip Ethernet forum for identifying this problem.
  7. Cleaned up some C30 compiler warnings related to macro definitions with inadequate parenthesis in them.
  8. Fixed HTTP2 module sometimes returning a 501 error instead of a correct web page when being bombarded with new connection requests.
  9. Fixed a TickGet*() API problem where the returned tick value could be off by 64K ticks occasionally on PIC24 and dsPIC processors.

10.Fixed SMTP client module failing to send email when attempting to send an email with a `CC' or `BCC' field that was in ROM while the `To' field was in RAM or visa versa. 11.Fixed TCP module sending an incorrect sequence number in RST packets sent when in the TCP_SYN_SENT state and an invalid segment arrives. In prior stack versions, some TCP client applications might take a very long time to recover in the event of a power failure, reset, and subsequent reconnect to a remote server that still thinks the old connection is still active. With this fix, reconnections should be possible almost immediately after a power failure because the correct RST packet will cause the old connection to get closed right away. 12.Fixed a TCP socket leak problem that would occur over if the local PIC called TCPDisconnect() and the remote node didn't send us a correct FIN response. Sockets could previously get lost in the TCP_FIN_WAIT_2 state and wouldn't recover unless the application called TCPDisconnect() a second time with the same socket handle.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. TFTPc module has not been tested with this version.
  3. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  4. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail.
  5. HI-TECH PICC-18 projects will not correctly set the processor configuration fuses through code using the __CONFIG() macro. Ensure that the configuration fuses are manually set correctly via the MPLAB IDE Configuration Bits dialog. This problem has been observed with compiler version 9.50PL3.
  6. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate MAX_TCP_SOCKETS, TCP_TX_FIFO_SIZE, TCP_RX_FIFO_SIZE, or MAX_HTTP_CONNECTIONS.
  7. GenericTCPClient example of downloading a web page from www.google.com is extremely slow. The default TCP socket has too little RX space to accept a full packet sent from Google's servers, so the remote server must retransmit a lot of data, slowing the transfer down a lot. Making TCP_RX_FIFO_SIZE 536 bytes or bigger and correspondingly shrinking MAX_TCP_SOCKETS will correct this problem.

******

v4.11 27 August 2007

******

IMPORTANT NOTE: You must use MPLAB 7.62 or higher to successfully open the MPLAB projects.

Changes:

  1. Added a Microchip TCP/IP Stack Users' Guide to document the stack features/modules/and APIs and address the stale AN833 documentation. Note that this is a work in progress. Many modules have yet to be documented in the Users' Guide.
  2. Added HTTP2 module. This HTTP module includes a whole new API and supreme new features, such as POST support, cookies support, browser authentication support, and more.
  3. Added MPFS2 module. This module is required for the new HTTP2 module and performs better while having fewer limitations. Long filenames and folders are now supported.
  4. Added a new GUI based MPFS2.exe PC utility. The older MPFSv2.exe GUI application and MPFS.exe command line tool has been retired. The new utility has advanced features, such as MPFS2 file format support, GZIP compress, etc.
  5. Added a TFTP bootloader. This is a stand alone project and currently only supports the PIC18F97J60 family of PIC processors with internal Ethernet.
  6. Added UART2TCPBridge.c file and STACK_USE_UART2TCP_BRIDGE option to TCPIPConfig.h. This new module acts as a TCP and UART bridge, with a high priority UART interrupt and dedicated UART TX and RX FIFOs for minimum UART latency and maximum performance. By default, the bridge acts as a TCP server and listens on port 9761. The UART baud rate defaults to 19200. The bridge can be reconfigured to act as a TCP client.
  7. Added Simple Network Time Protocol (SNTP) client. This module automatically obtains the current time (date) from the Internet. Enable this module by defining STACK_USE_SNTP_CLIENT in TCPIPConfig.h. Obtain the current time (in seconds since 00:00:00 1970) by calling the SNTPGetUTCSeconds() API.
  8. Added support functions Base64Encode() and Base64Decode() in Helpers.c. Base 64 is required for the new HTTP2 module, but of general use to many applications.
  9. Added SMTP Authentication support to the SMTP Client. To use this, set the SMTPClient.Username and SMTPClient.Password string pointers to a non-NULL value before calling SMTPSendMail(). Applications implementing email transmission capabilities should expose these options to the end-user for configuration. To use SMTP servers that do not support the AUTH LOGIN authentication command, simply leave the SMTPClient.Username and SMTPClient.Password pointers as their default NULL value.

10.Converted DHCPDisable() from a macro to a real function and added the complementary DHCPEnable() function. These two functions can be used at run time to dynamically switch between using a static IP address and configuration and DHCP assigned IP address and configuration. 11.Updated StringToIPAddress() to work more robustly, including the ability to decode host name strings and determine if they contain a valid IP address or not. Also, the complementary ROMStringToIPAddress() function was added. 12.Updated the DNS module. Now, if you give it an IP address string to resolve, it will convert the string to an IP address and immediately return without querying the DNS. 13.Shrunk the advertised TCP Maximum Segment Size from 576 bytes to 528 bytes. This might improve compatibility if your TCP data has to propagate over nodes with small MTUs and you have a correspondingly large TCP RX FIFO defined. 14.Performed some maintenance on the FTP.c file. No significant functionality has been changed, but some potential problems were corrected. 15.Altered Tick.c file and API. Now, the Tick module can operate maximum precision, returning the value of the actual Timer as it is counting, without disturbing the timer count by writing to it or disabling it. Three new APIs were added, TickGetDiv256(), TickGetDiv64K(), and TickConvertToMilliseconds(). Internally the tick counter is now 48-bits wide and as accurate as your Timer clock source, allowing you to use it as a Real Time Clock. 16.Added PIC24FJ64GA004_PIM hardware profile. This hardware profile is intended for use with the PIC24FJ64GA004 PIM on the Explorer 16 development board. In this mode, BUTTON2 and BUTTON3 and several of the LEDs do not work correctly due to lack of I/O pins on this device. Also, you cannot have the POT and TEMP jumpers on the PIM bridged because these signals are multiplexed with the SDO1/SDI1 pins needed for the Ethernet PICtail Plus. 17.Removed most ROM APIs when using a 16-bit compiler (C30). PIC24s and dsPICs usually don't need separate ROM functions since the Program Space Visibility feature maps ROM into RAM space. All ROM APIs are still supported, but they are now macros to base RAM APIs. This change saves a couple of kilobytes of code space on PIC24 and dsPICs. 18.Improved MyTCB structure caching. This should reduce TCP packet processing overhead with the ENC28J60 where TCBs are stored in the Ethernet RAM. 19.MAX_RETRY_COUNTS TCP configuration option has been renamed to TCP_MAX_RETRIES. 20.FTP server is no longer enabled by default. HTTP2 now supports POST, so you can upload new webpages through the /mpfsupload page now. FTP required two precious TCP sockets. 21.Began adding hooks for an SSL/TLS transport for secure HTTPS and other future stack modules. Note that these cryptographic modules are not available at this time. Configuration options such as MAX_SSL_CONNECTIONS do nothing and should not be modified. 22.Username has changed for all of the modules. Now all modules have a default username of "admin" and password of "microchip". Previously, the FTP and Telnet modules used "ftp" and "telnet" respectively for the usernames.

Fixes:

  1. Fixed a SendFile() bug in HTTP.c where parsing dynamic cgi files could send garbage back to the web browser sometimes. Thanks go to Matt Watkins on the Microchip Ethernet forum for identifying this issue.
  2. Fixed an off by one error in the calculation of RESERVED_TCP_MEMORY. Previously, the last TCP socket's RX FIFO would incorrectly overlap with the Ethernet RX buffer, causing incoming packets to occasionally be corrupted or the incoming data on the last socket to get corrupted.
  3. Fixed the QWORD_VAL's dword struct element types. dword.LD and dword.HD were incorrectly defined as WORDs instead of DWORDs. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for identifying this issue.
  4. Fixed the incorrect processing of received IP fragments with a non-zero offset. This stack does not support IP packet reconstruction due to the limited amount of available RAM. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for noticing this behavior.
  5. Board now only responds to ping requests to our IP address, the directed subnet broadcast address, or the broadcast address of 255.255.255.255. Previously, it would respond to any ping request to any IP address, assuming the MAC address was correct.
  6. Fixed a memory corruption/UDP packet loss problem when handling incoming UDP packets. Previously, StackTask() would incorrectly continue processing more packets if it came upon a UDP packet. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for identifying this issue.
  7. Fixed the SMTPClient.ROMPointers.Server flag having an inverted meaning. Previously, the SMTP client module would treat the SMTPClient.Server pointer as a ROM pointer if this bit was cleared. In most cases, this would cause the SMTP client to return an error code of 0x8000 when the SMTPClient.SMTPServer address pointer was set.
  8. Fixed the DHCP Server module from incorrectly parsing received packets which had a DHCP_PARAM_REQUEST_IP_ADDRESS option followed by more options. Previously due to the length miscalculation, the parser would enter a random state, depending on the packet's contents. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for identifying this issue.
  9. Fixed potential incorrect results when UDPIsGetReady() was called and a previous application did not call UDPDiscard() on an RX packet. Now, StackTsk() calls UDPDiscard() as appropriate to let it know when it's old RX data is being thrown away. This fixes a potential bug in the DHCP Server module and makes the UDP API more robust. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for identifying the potential DHCP server issue.

10.Fixed a potential ARP bug where the Gateway's MAC address would be returned for an IP address on the local subnet. This unusual case would occur when two application tasks were using the ARP module at the same time and the second application was trying to resolve an IP address off of our subnet. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for pointing this issue out. 11.Fixed an PIC18F97J60 family MAC layer bug where MACGetArray() might not correctly increment the Ethernet read pointer if a NULL pointer was given for the destination. The C compiler might have optimized the function so that it would increment the read pointer one less than it was supposed to. 12.The TCP module now acknowledges TCP Keep-Alive packets which will help prevent connection loss if the remote node fills up our RX FIFO and then our window-update packet gets lost on the network/Internet. In stack version 4.02, a zero-window probe would have been required to restore the communications. 13.Fixed a TCP RX FIFO corruption issue that would occur in (uncommon) circumstances when too many out-of-order segments arrived such that a second "hole" would have been required to accommodate the data. Thanks go to Iñaki Esparza and his eagle eyes on the Microchip Ethernet forum for finding this corner case bug. 14.Inline assembly in the ETH97J60.c file has been modified to accommodate the C18 Extended mode and C18 Auto default storage class. Previously, the Ethernet module would transmit garbage packets when using the C18 parameter stack. 15.Fixed potential buffer overflow in NBNS.c's NBNSGetName() function where an unexpected string length retrieved from the packet could cause random memory corruption. 16.Fixed some potential PIC18F97J60 family Ethernet module transmit lockup conditions that occur on some networks. Previously blocking while() loops would wait indefinitely for the ECON1bit to become clear by hardware, which the hardware might never have done. 17.In MainDemo.c, a call to DelayMs() was being made using a value of 100ms. This was too long for the underlying Delay1KTCYx() C18 function and would result in a shorter than expected delay when compiled with C18. This has been fixed with a loop. Thanks go to Andy123 on the Microchip Ethernet forum for pointing this problem out. 18.Fixed a potential C18 memory overlaying problem in the TickUpdate() function. Previously, the local variable used in this function might have been overlayed on other memory, resulting in random memory corruption as the ISR occurred. 19.The demo AJAX web pages in the TCPIP Demo AppWebPages folder now correctly display and self-refresh in Firefox 2. Previously, it would work in Firefox 1.5 and Microsoft Internet Explorer, but not Firefox 2. Thanks go to "gohsthb" on the Microchip Ethernet forum for identifying this correction. 20.Rewrote the GenericTCPServer.c example to not use an application RAM FIFO for buffering. Since the TCP module implements its own FIFOing, the application has limited need for its own FIFO too. This fixes a previous bug where the GenericTCPServer was not checking the number of incoming bytes with the remaining size available of the App FIFO. This would have previously resulted in a buffer overflow, corrupting the RX data if too much arrived all at once. 21.Fixed a potential MPFS classic inline ASM30 assembly code problem where web pages stored in internal Flash and C30 with optimizations enabled could result in data corruption. 22.Fixed a UDPPut() tracking problem that would result in extra bytes being appended to the end of a packet if the UDPSetTxBuffer() function was used. This previously caused the SNMP module to send some junk data at the end of its packets. 23.Fixed a potential TCP problem where transmitted FIN packets might not get retransmitted properly if the remote node never acknowledged the data that was transmitted just before the FIN was sent. 24.Fixed a NetBIOS Name Service bug where the response packet would sometimes get sent to an incorrect address. It now consistently responds to the unicast MAC/IP address of the NBNS query packet. 25.Added padding to all transmitted DHCP messages to make the minimum UDP payload at least 300 bytes. This fixes compatibility with some older BOOTP relay devices which discard smaller packets. Thanks go to Dave Collier on the Microchip Ethernet forum for pointing this problem out. 26.Substantially shrunk the number of retransmission attempts made in the TCP_SYN_RECEIVED state. This improves recovery time when attacked by a SYN flood Denial of Service event. The recovery time is now 7 seconds (3 total packets) instead of 31 seconds (6 total packets) 27.Fixed the possibility of the NetBIOS Name Service module giving out the board's static IP address before a DHCP lease could be obtained. NBNS requests are now only serviced when originating from nodes on the same subnet. 28.Fixed storage of MPFS classic in internal program memory when using the HI-TECH PICC-18 compiler. 29.Substantially revised TCP.c, fixing many TCP bugs and possibly adding new ones. Thanks go to Michael Rubinstein for finding several of these TCP problems. 30.The DNS client module will now time out and return failure if the DNS server cannot be ARPed or does not respond to the DNS query. Each timeout is set to 1 second and 3 total ARP and 3 total DNS query attempts are possible. Previously, it would retry indefinitely, causing the calling application to deadlock.

Known Problems:

  1. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  2. TFTPc module has not been tested with this version.
  3. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server.
  4. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail.
  5. HI-TECH PICC-18 projects will not correctly set the processor configuration fuses through code using the __CONFIG() macro. Ensure that the configuration fuses are manually set correctly via the MPLAB IDE Configuration Bits dialog. This problem has been observed with compiler version 9.50PL3.

Testing and Performance Notes:

  1. Make sure to use MPLAB IDE 7.62 or higher with this version. Versions below 7.61 will not work. Version 7.62 has cool new features like C auto-word complete and function parameter tooltips that can be enabled (disabled by default).
  2. Testing was done using MPLAB C18 version 3.12, MPLAB C30 version 3.01, and HI-TECH PICC-18 version 9.50PL3. Make sure to upgrade your tools to at least these versions.

******

v4.02 10 April 2007

******

IMPORTANT NOTE: You must use MPLAB 7.41 or higher to successfully open the MPLAB projects. IMPORTANT NOTE2:If an external serial EEPROM memory is used to store AppConfig, it's contents will be invalidated the first time you run this version, restoring the AppConfig defaults. The AppConfig structure has been optimized. IMPORTANT NOTE3:If an external serial EEPROM memory for MPFS, you will need to recreate the MPFS image and program your EEPROM. A 32 bit addressing format is now used.

Changes:

  1. Implemented TCP RX packet order correction logic. The stack can now accept TCP frames that arrive out-of-order without requiring the remote node to go through a retransmit cycle. This dramatically improves RX performance when communicating over the Internet.
  2. UDPOpen() now can handle a NULL pointer for remoteNode. In this case, the broadcast IP/MAC addresses will be used for the remoteNode (destination address of outbound packets).
  3. Recreated MPLAB projects for the HI-TECH PICC-18 compiler. These were temporarily absent from 4.00RC. This project works with the PIC18F97J60 with internal Ethernet module, assuming the correct compiler version is present.
  4. Moved all the headers around. Most of them are in "Microchip SolutionsMicrochipIncludeTCPIP Stack" now. This change was made to again be more compatible with other (future) Microchip software libraries.
  5. New UDPPut() behavior. Now, if space in the Ethernet TX buffer runs out, the packet will not automatically be transmitted. You must call UDPFlush() to cause the packet to be transmitted.
  6. Added UDPGetArray(), UDPPutArray(), UDPPutROMArray(), UDPPutString() and UDPPutROMString() user API functions. These functions perform substantially better than calling UDPPut() successively and allow greater application programming flexibility.
  7. Changed TCPPutString() and TCPPutROMString() APIs to now return an updated string pointer instead of a count of bytes successfully placed in the TX buffer.
  8. Added UDPPerformanceTest.c. By default this module causes UDP packets containing 1024 bytes of application data to be broadcasted on UDP port
    1. Use a packet sniffer, such as Wireshark (http://www.wireshark.com/)

to capture and derive stack overhead/UDP TX performance characteristics with this module. Note that this test uses the UDPPutROMArray() function. Applications which use successive calls to UDPPut() will be slower. To enable this module, #define STACK_USE_UDP_PERFORMANCE_TEST in TCPIPConfig.h.

  9. Added TCPPerformanceTest.c. By default this module listens on TCP port
    1. When a remote client connects, this server module will being

transmitting the maximum possible amount of application data that it can, given your TCP TX FIFO size. Use a packet sniffer, such as Wireshark (http://www.wireshark.com/) to capture and derive stack overhead/TCP TX performance characteristics with this module. Any TCP client can be used, including readily available utilities such as the telnet.exe utility available on Microsoft Windows XP. To use it to connect to the test module, run: "telnet.exe xxx.xxx.xxx.xxx 12345" where xxx.xxx.xxx.xxx is the board's IP address. Note that this test uses the TCPPutROMArray() function. Applications which use successive calls to TCPPut() will be slower. To enable this module, #define STACK_USE_TCP_PERFORMANCE_TEST in TCPIPConfig.h. 10.Added Reboot.c module. By default, this module listens on UDP port 30304. If the application byte 0x00 arrives on this port, the PIC will reset. This is primarily useful for remote Bootloader entry. #define STACK_USE_REBOOT_SERVER in TCPIPConfig.h to enable this module. Note that since no encrypted challenge/response algorithm is currently implemented, this module is a Denial of Service vulnerability, so it should not be enabled unless there is a specific need for it. 11.Made the TickUpdate() ISR routine execute in the low priority ISR instead of the default high priority ISR. The Microchip TCP/IP stack does not need any interrupts except this low priority timer. 12.Renamed STACK_USE_DHCP macro to STACK_USE_DHCP_CLIENT 13.Added STACK_USE_MPFS macro. 14.Changed UDPIsPutReady() to return a WORD instead of a BOOL. The WORD is the number of bytes that can be put into the buffer. 15.Changed MACGetArray() to accept a NULL pointer. If NULL, the retrieved data will simply be discarded. This also changes the behavior of UDPGetArray() and TCPGetArray() to match, throwing bytes away if a NULL pointer is given. 16.Added a very simple DHCP Server module. This module has limitations and is useful for a single client only. Its purpose is to allow you to directly connect the board to a standard PC through a crossover cable (no other network nodes attached). The server is coded to automatically disable itself if the DHCP client is also enabled and another DHCP server is detected on the network. This allows both the DHCP server and DHCP client to coexist without any manual reconfiguration. 17.Added DNSResolveROM() function for resolving host names that are stored in program memory, ex: literal strings. 18.Added a TCP automatic transmit/window update timer. It defaults to TCP_AUTO_TRANSMIT_TIMEOUT_VAL (40ms) after the first get or put operation following the last automatic transmit/window update. This timer enhances performance, especially when streaming data over the Internet where round trip times can be several tens to low hundreds of milliseconds. This also improves application coding flexibility as TCPFlush() need not be called anymore. 19.Added TCP delayed ACKnowledgement timer. This conserves bandwidth by transmitting fewer ACKs and prevents inadvertently influencing remote slow start/collision avoidance and fast retransmit algorithms. 20.Completely rewrote ICMP (ping) server module. It is now much smaller (ROM and RAM), faster, and can handle packets of 576 bytes or larger, if no IP fragmentation occurs. 21.Rewrote StackTsk() stack manager. It is much simpler now. 22.Added TCPFind(), TCPFindArray(), and TCPFindROMArray() user API functions. These functions peek inside a given TCP socket's RX FIFO (without removing anything) and looks for a particular byte or array of bytes. This should greatly simplify the creation of application code whenever variable length fields are used (ex: text strings terminated by rn). It supports case insensitive text searching or binary searching, as well as an offset to start searching at. 23.Added TCPGetRxFIFOFree() user API. It returns the number of bytes of free space in the TCP's RX FIFO. 24.Changed default TICK resolution to 1ms (from 10ms) and improved accuracy. 25.Added outbound ping capabilities (i.e. board can now ping another board or a PC). To enable these features, define STACK_USE_ICMP_CLIENT. This will enable several new APIs, including ICMPBeginUsage(), ICMPSendPing(), ICMPGetReply(), and ICMPEndUsage(). The functions should be called in this order. See the PingDemo() function in MainDemo.c for an example of how to use them. By default, pushing BUTTON3 (left-most one) will cause a ping to be sent to 4.78.194.159 (ww1.microchip.com). The response time will be displayed on the LCD (assuming your development board has an LCD). 26.Cleaned up C30 3.00 signed/unsigned warnings. 27.Removed PIC18F97J60_TEST_BOARD hardware profile support. This stack no longer supports it due to the old beta silicon (with errata) mounted on these boards. 28.Added support for ROM pointers for all of the SMTP strings (To, From, CC, Subject, etc.). If you use a ROM string, you must also set the corresponding SMTPClient.ROMPointers.xxx bit to let the SMTP module know which type of pointer was provided. See the SMTPDemo() code in MainDemo.c for and example calling sequence using both ROM and RAM strings for the various fields.

Fixes:

  1. Fixed a critical TCP buffer corruption issue where the start of a TCB header overlapped with the last byte of the RX FIFO from the previous socket. This bug affected version 4.00RC only.
  2. ETH97J60.c, TCPIP.h, and TCPIP Stack Version.txt were correctly readded to the TCPIP Demo App-C18 project using relative paths instead of absolute paths.
  3. UDPOpen() now dynamically assigns a local port number if you call it and give it a 0x0000 port number. This should fix some UDP applications from not working (ex: DNS Client module) with some computers/routers/networks which throw away traffic originating from the invalid port 0x0000 value.
  4. Fixed a ENC28J60 bank selection error that would occur if an application called GetCLKOUT() in ENC28J60. By default, this function is not called.
  5. UnencodeURL() function in Helpers.c is now tested and working.
  6. Fixed a TCP Window Update problem when TCPGetArray() was used. Before the problem was fixed, performance could have been terrible on reception.
  7. Fixed a unintended TCP connection close if the socket was idle for about a minute. Now, TCP sockets will remain open indefinitely if there is no traffic going on.
  8. Serial numbers >32K are now displayed correctly on the serial port as a positive value when C18 is used and the board is placed in configuration mode (BUTTON0 is depressed on power up).
  9. HI-TECH PICC-18 compiler would previously incorrectly initialize the AppConfig structure.

10.Previously a processor reset was possible when accessing items in the AppConfig strucutre on 16 bit MCUs (PIC24, dsPIC) due to unaligned word accesses. This was fixed by reordering the Flags byte in the APP_CONFIG structure. 11.Rewrote DHCP client state machine, fixing the previously known problem where it would not perform a new discovery if it was trying to renew a lease with an offline DHCP server. 12.Fixed a critical deadlock problem in the ETH97J60.c MAC layer driver for the PIC18F97J60 family Ethernet controller. Previously, it was possible (although rare) that the DMAST or TXRTS bits would get stuck set if too much Ethernet traffic was received within a short interval. Previously, the MACFlush() function was unnecessarily setting TXRST, which it should not do while the Ethernet interface or DMA is being used. 13.Fixed an HTTP server state machine problem where a new connection occurring too soon on a previously used socket could cause the HTTP server to no longer respond. 14.Fixed a potential memory corruption error in the HTTPGetVar() callback which would exceed the bounds of the VarString array when returning the VAR_STACK_DATE variable. 15.Fixed a TCP transmission sequence tracking problem whenever data is retransmitted and new unflushed data is also in the TX FIFO. Thanks go to Matt Watkins on the Microchip Ethernet forum for identifying this issue.

Known Problems:

  1. RTL8019AS MAC layer driver has not been updated for new TCP module. Users requiring RTL8019AS support should continue to use stack version 3.75.
  2. I2CEEPROM.c has not been tested or completed. Continue to use I2CEEPROM.c from stack version 3.75 if this file is needed.
  3. Telnet server module does not implement a lot of Telnet functions. As a result, it will likely not display correctly or work at all with some Telnet clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows.
  4. TFTPc module has not been tested with this version.
  5. The default demo web pages which use AJAX do not automatically refresh themselves when viewed in Firefox 2.0.0.1. Earlier Firefox versions (1.5ish) probably work without any problem.
  6. Files may be inaccessible in your MPFS if compiled with C18 for internal flash program memory and your total MPFS content is large (around 64KB or larger). The code attempts to access the ROM memory using a near rom pointer when a far rom pointer is needed.
  7. If using MPLAB 7.52 all .s files that are compiled with C30 will not have the corresponding object file get stored in the correct directory. As a result, if you are compiling with C30 and with MPFS_USE_EEPROM not defined (i.e. storing web pages in internal program memory), the project won't link (throws a undefined reference to `MPFS_Start'). As a workaround, remove the Intermediates Directory in the MPLAB project. Alternatively upgrade MPLAB to a newer version. MPLAB IDE 7.60+ may have this fixed.
  8. If the DHCP client and DHCP server are used at the same time and you connect two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to renable it's DHCP server.
  9. HI-TECH PICC-18 projects may not compile when MPFS_USE_EEPROM is not defined and you are trying to store web page data in internal FLASH program memory.

10.HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail.

Testing and Performance Notes:

  1. This stack version was compiled and tested with the following tool versions: -MPLAB IDE 7.52 -Microchip C30 version 3.00 -Microchip C18 version 3.10 -HI-TECH PICC-18 version 9.50PL3
  2. Using the UDPPerformanceTest.c module, the stack can transmit around 220KBytes/second (1.75Mbits/second) of UDP application data on the PIC18F97J60 with internal Ethernet @ 41.66667MHz core clock, compiled using C18 3.10 with debug optimization settings.
  3. Using the UDPPerformanceTest.c module, the stack can transmit around 392KBytes/second (3.14Mbits/second) of UDP application data on the PIC24HJ256GP610 with external ENC28J60 @ 40 MIPS, compiled using C30 3.00 with debug optimization settings.
  4. Using the TCPPerformanceTest.c module, the stack can transmit around 58KBytes/second (464Kbits/second) of TCP application data on the PIC18F97J60 with internal Ethernet @ 41.66667MHz core clock, compiled using C18 3.10 with debug optimization settings, over Ethernet when using a tiny 200 byte TX TCP FIFO. Note that performance can be improved significantly by increasing the FIFO size and performance will drop significantly if the round trip TCP acknowledgement time is increased (ex: testing over the Internet instead of Ethernet).
  5. Using the TCPPerformanceTest.c module, the stack can transmit around 69KBytes/second (558Kbits/second) of TCP application data on the PIC24HJ256GP610 with external ENC28J60 @ 40 MIPS, compiled using C30 3.00 with debug optimization settings, over Ethernet when using a tiny 200 byte TX TCP FIFO. Note that performance can be improved significantly by increasing the FIFO size and performance will drop significantly if the round trip TCP acknowledgement time is increased (ex: testing over the Internet instead of Ethernet).
  6. Using the TCPPerformanceTest.c module, the stack can transmit around 178KBytes/second (1.42Mbits/second) of TCP application data on the PIC24HJ256GP610 with external ENC28J60 @ 40 MIPS, compiled using C30 3.00 with debug optimization settings, over Ethernet when using a larger 2000 byte TX TCP FIFO. Note that performance will drop significantly if the round trip TCP acknowledgement time is increased (ex: testing over the Internet instead of Ethernet).

******

v4.00RC 28 December 2006

******

IMPORTANT NOTE: If an external serial EEPROM memory is used to store AppConfig, it's contents will be invalidated the first time you run this version, restoring the AppConfig defaults. The AppConfig structure has been optimized. IMPORTANT NOTE2: If an external serial EEPROM memory for MPFS, you will need to recreate the MPFS image and program your EEPROM. A 32 bit addressing format is now used.

Changes:

  1. Added Simple Mail Transfer Protocol (SMTP) client module and updated MainDemo.c to exercise the Email transmission functionality when a user pushes BUTTON0.
  2. Added beta Telnet server module. See Known Problems section.
  3. Completely revamped the TCP module. A real transmit FIFO and receive FIFO are allocated for each TCP socket now. This greatly enhances RFC compliance, communications robustness, and makes application development easier. New APIs were added for putting and getting arrays and strings (including ROM variants). Several TCP related bugs are now fixed as a result. Please report any bugs found in the new implementation.
  4. Added TCPPutArray() API.
  5. Added TCPPutROMArray() API.
  6. Added TCPPutString() API.
  7. Added TCPPutROMString() API.
  8. Added TCPGetArray() API.
  9. Changed TCPIsPutReady() API. Instead of returning a BOOL, it now returns a WORD. The WORD is a count of the number of bytes that TCPPut(), TCPPutArray(), etc. can immediately place in the output buffer. MAKE SURE THAT YOUR CODE DOES NOT COMPARE THE RETURN RESULT OF TCPIsPutReady() DIRECTLY TO TRUE. For example, "if(TCPIsPutReady(MySocket) == TRUE){...}" must be converted over to: "if(TCPIsPutReady(MySocket)){...}".

10.Changed TCPIsGetReady() API. Instead of returning a BOOL, it now returns a WORD. The WORD is a count of the number of bytes that TCPGet() or TCPGetArray() can immediately obtain. MAKE SURE THAT YOUR CODE DOES NOT COMPARE THE RETURN RESULT OF TCPIsGetReady() DIRECTLY TO TRUE. For example, "if(TCPIsGetReady(MySocket) == TRUE){...}" must be converted over to: "if(TCPIsGetReady(MySocket)){...}". 11.Changed TCPDiscard() return type from BOOL to void. 12.Removed TCP_NO_WAIT_FOR_ACK option. It was defaulted to disabled in the last two releases of the stack and is not needed with the new TCP module. 13.Updated DNS module to include two new required APIs: DNSBeginUsage() and DNSEndUsage(). These functions control a one bit ownership semaphore to allow multiple applications to use the DNS module in series. If invoked correctly, this will prevent unintended bugs resulting from two applications trying to use the DNS module at the same time. Old applications, such as those based around the GenericTCPClient.c example must be updated to use these functions. 14.Started using a new project structure and folders. You must use MPLAB 7.41 or higher (stack is tested on MPLAB 7.50) to use the default workspaces/projects, which include files using relative paths. This should improve compatibility with some future code libraries released by Microchip. StackTsk.h was broken into TCPIPConfig.h, HardwareProfile.h, and StackTsk.h. TCPIPConfig.h now includes all stack configuration options and HardwareProfile.h contains all hardware options. No macros need be globally defined in MPLAB project now. TCPIP.h is the only header applications must include now, for any/all modules used. 15.Combined ARP.c/ARP.h and ARPTsk.c/ARPTsk.h into a single file pair: ARP.c/ARP.h. Applications built using a prior stack revision must remove all instances including "ARPTsk.h" and replace it with "ARP.h" instead. The ARP module is now simpler, more linear (easier to read), and being in one source file, allows the C compiler to optimize better. 16.Added PIC18F67J60_TEST_BOARD hardware profile to HardwareProfiles.h. This hardware profile is designed for 05-60091 (Rev 1), a development board that is not in production at this time. 17.Added DSPICDEMNET1 and DSPICDEMNET2 hardware profiles to HardwareProfiles.h for eventual support of the Microchip dsPICDEM.net 1 and dsPICDEM.net 2 demo boards. These two boards use the RTL8019AS Ethernet controller and a 24LC515 EEPROM. These changes are currently incomplete and these profiles cannot be used. 18.Began rewriting I2CEEPROM.c to support 16 bit CPUs, including the dsPIC30F6014 used on the dsPICDEM.net 1 and 2 demo boards. Note that work here is incomplete and cannot be used as a result -- see Known Problems section. 19.Partially updated RTL8019AS.c to support 16 bit CPUs, including the dsPIC30F6014 used on the dsPICDEM.net 1 and 2 demo board. Note that work here is incomplete and cannot be used as a result -- see Known Problems section. 20.Updated SNMP.c to use new typedefs in GenericTypedefs.h. Also SNMP was tested in this version. SNMP.mib was updated some to better reflect current hardware. 21.Added AN870 SNMP callbacks to MainDemo.c (a feature that was missing in 3.xx releases). This code will get compiled when STACK_USE_SNMP_SERVER is defined in TCPIPConfig.h. 22.Removed all instances of MPFS_USE_PGRM for storing in internal FLASH program memory. Storage in internal program memory is now the default. Define MPFS_USE_EEPROM to override the default and store MPFS in an external EEPROM memory. 23.Decreased program memory needed for Announce.c module by about 180 bytes. Multiple inline calls to UDPPut() were removed. 24.UDP checksum checking logic has been improved. The UDP layer now avoids writing the pseudo header checksum in the RX buffer. 25.Swapped endianess of the returned checksum from CalcIPBufferChecksum(). Rewrote CalcIPBufferChecksum() in Helpers.c. This improves consistency. 26.Improved swapl() in Helpers.c. 27.Improved USART baud rate (SPBRG) calculation for PIC18s. Rounding is now done to chose the most optimal value and the code will automatically select high baud rate mode (BRGH=1) if possible. Additional improvements can be made if using a newer PIC18 with the 16 bit baud rate generator. 28.Added GenericTCPServer.c example file to complement GenericTCPClient.c. The server is enabled by defining STACK_USE_GENERIC_TCP_SERVER_EXAMPLE in TCPIPConfig.h. 29.Renamed STACK_USE_GENERIC_TCP_EXAMPLE definition to STACK_USE_GENERIC_TCP_CLIENT_EXAMPLE for consistency with new server example. 30.Defaulted MPFS.exe to generate binary MPFS images using 32 bit addressing. MPFS.h has been modified to also default to use 32 bit addressing of external EEPROM images. You must rebuild any old MPFS images and reprogram them if upgrading from a previous TCP/IP stack revision, which defaulted to use 16 bit addressing. 31.Updated MPFS.exe to #include "TCPIP.h" instead of "..HeadersCompiler.h" in C files generated by the utility. 32.Added MPFSv2.exe PC utility for generating large MPFS images in program memory (ASM30 code) for C30 users. Previously, the C30 compiler placed a limit of less than 32KB of total MPFS size due to the PSV window size limitation on PIC24/dsPIC devices. To get around the limitation, use the new MPFSv2.exe utility to generate an .s file which can be included in your project instead of the .c file generated by the traditional MPFS.exe utility.

Fixes:

  1. Fixed a bug in ARPProcess() which would incorrectly send an ARP response to an incorrect MAC & IP address if a TX buffer wasn't immediately available.
  2. Fixed a TCP bug where TCPIsGetReady() would return TRUE even if no data was left in the recieved packet. Previously you had to call TCPGet() one last time and have it fail before TCPIsGetReady() would return FALSE.
  3. Modified TCP state machine. Established connections will no longer automatically close if left idle for approximately 45 seconds. Note that your application needs to ensure that no sockets unintentionally get lost (For example: a server socket that received data only is established and the cable breaks while connected. In this case, the socket would never be detected as being disconnected since the server never attempts to transmit anything).
  4. Stopped overclocking dsPIC33 and PIC24H devices. Previously PLLFBD was incorrectly set to 39 instead of 38 to yield a resulting Fosc of 84MHz (42MIPS) instead of 80MHz (40MIPS) with the default Explorer 16 development board. Thanks go to Matt Watkins on the Microchip Ethernet Forum for pointing this error out.
  5. Corrected a bug in IP.c where IPHeaderLen would not be properly initialized if a NON_MCHP_MAC was used (ex: RTL8019AS) and IPSetRxBuffer() was called. This bug did not affect ENC28J60 or PIC18F97J60 family support. Thanks go to Darren Rook for identifying this issue.
  6. Updated checksum checking code in ENC28J60.c for latest silicon DMA checksum errata.
  7. Declared TickCount in Tick.c/Tick.h as volatile and implemented an interrupt safe reading procedure in TickGet(). Since this multibyte variable is modified in the ISR and read in the mainline code, these changes are needed to prevent rare inconsistency bugs.
  8. Fixed Announce.c so the unicast remoteNode of the requesting packet would be used rather than the remoteNode of the last received packet, which may not be correct when transmitting. Thanks go to Brett Caulton for identifying this issue.
  9. Fixed a DHCP bug which would cause DHCP renewals to continually occur after only 60 seconds once the original lease expired. Thanks go to Brett Caulton for identifying this issue and fix.

10.Fixed a potential TCP socket leak in the FTP module. Previously FTPDataSocket would not be reliably initialized nor closed if the connection was killed forcefully (user killed application, cable disconnected while transferring, etc.).

Known Problems:

  1. RTL8019AS MAC layer driver has not been updated for new TCP module. Users requiring RTL8019AS support should continue to use stack version 3.75.
  2. I2CEEPROM.c has not been tested or completed. Continue to use I2CEEPROM.c from stack version 3.75 if this file is needed.
  3. Telnet server module is still in development. No user authentication features are currently implemented. Some telnet clients may render the telnet server output incorrectly (in the wrong locations or wrong colors). Testing has only been done with the Microsoft Windows telnet.exe utility that comes Windows XP.
  4. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease is offline. The board will continue to use the expired IP address until the DHCP server comes back online, at which point the lease will be renewed or a new discovery will occur. A new discovery should occur after timing out, instead. It is believed that this problem has always existed in previous stack revisions.
  5. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease does not include Option 54, the Server Identifier. A new discovery should occur after timing out. It is believed that this problem has always existed in previous stack revisions.
  6. TFTPc module has not been tested with this version.
  7. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up).

******

v3.75 14 August 2006

******

Changes:

  1. Added beta DNS client module (DNS.c). DHCP was also updated to obtain a DNS server address. Added AppConfig.PrimaryDNSServer IP address. Added STACK_USE_DNS configuration macro. To use the DNS client, call DNSResolve() with the server name, ex: DNSResolve("www.microchip.com"), and then periodically call DNSIsResolved() until it returns TRUE, ex: DNSIsResolved(&IPAddressDestination). Only one DNS resolution can be in progress at a time. Because the DNS client is a beta module, the API or code may change before being finalized. No formal DNS API documentation is available yet.
  2. Added beta NetBIOS Name Service responder module (NBNS.c). Added AppConfig.NetBIOSName string. Added STACK_USE_NBNS configuration macro. Added MY_DEFAULT_HOST_NAME macro in StackTsk.h. Now, whenever a NetBIOS broadcast attempting to resolve AppConfig.NetBIOSName arrives, a response will be made. This form of name resolution only works on a single subnet. Off the subnet, manual registration in a DNS server or other means will be needed to allow the local Host Name to be recognized and translated to an IP address. The default NetBIOS name for the board is "MCHPBOARD". To test the NetBIOS Name Service module, try entering http://MCHPBOARD/ into your web browser instead of the board's IP address.
  3. Added beta HTTP client module (GenericTCPClient.c). This module demonstrates how to make a TCP client application. To test this module, uncomment the STACK_USE_GENERIC_TCP_EXAMPLE macro in StackTsk.h, recompile, and then press the BUTTON1 button while the stack is running. RemoteURL[] should be downloaded from ServerName[] and written to the UART. For the default values of ServerName[] and RemoteURL[], the HTML search page for "Microchip" will be fetched from "www.google.com" and written to the serial port. No formal documentation is available for this example yet.
  4. Added Embedded Ethernet Device Discoverer PC project to aid in embedded product discovery when connected to a network and demonstrate how to write PC applications which can communicate with embedded devices. The source code for this device is included. It can be built using the Microsoft Visual C# 2005 Express Edition compiler. At the time of stack release, this 3rd party PC development tool can be downloaded at no cost from http://msdn.microsoft.com/vstudio/express/. If using only the Microchip Device Discoverer executable file without the Visual C# compiler, the .NET Framework 2.0 must be installed on the local PC. The application setup utility should allow dynamic downloading of this component if the target machine does not already have it installed.
  5. Updated Announce.c to listen and respond to discovery requests sent to UDP port 30303 starting with the character 'D'. To test this functionality, use the Embedded Ethernet Device Discoverer on a PC connected to the same subnet.
  6. Updated UART configuration menu to accommodate the new beta module configuration options (DNS server address, device host name).
  7. Increased MPFS reserve block to 64 bytes from 32. Also, because the APP_CONFIG structure was updated, all current MPFS images and data stored in deployed EEPROMs needs to be updated.
  8. Added a means to erase (invalidate) the onboard EEPROM using the BUTTON0 momentary switch (right-most switch on demo boards with multiple switches). To erase the EEPROM, hold down BUTTON0, RESET the board (press and release MCLR switch), and then continue to hold down BUTTON0 for an additional 4 seconds. If you press MCLR again, the EEPROM contents will now be invalid. If you press '0' on the UART, the same configuration that was read prior to invalidating the contents will be written back into the EEPROM. Invalidating the EEPROM allows the MY_DEFAULT_* constants to get loaded into a previously programmed EEPROM chip. Because of change #7, this procedure should be done for all currently programmed EEPROMs to prevent anomalous values from being read.
  9. remoteNode in StackTsk.c was changed from private to global scope. Now external modules can reference the address of the last received packet. Announce.c uses this to send a unicast response to a broadcast discovery request.

10.All stack modules that can be disabled (DHCP.c, FTP.c, etc) now will no longer emit a compiler error if you have it in the project without defining the appropriate macro (STACK_USE_DHCP, STACK_USE_FTP, etc). It will simply generate no machine code when compiled and the stack will not use that module. Make sure the proper macro is defined for each module that you wish to use. 11.Added SetRXHashTableEntry() to ENC28J60.c. This function can be used to set the appropriate bit in the Hash Table registers to join a particular multicast group. 12.Added Realtek RTL8019AS Ethernet controller support to the stack. MAC.c was renamed to RTL8019AS.c. This Ethernet controller is not recommended for new designs. RTL8019AS support was reintroduced to provide ongoing assistance to former Application designs implementing this chip. For new applications, use the Microchip ENC28J60 or PIC18F97J60 family of microcontrollers. 13.Added I2C EEPROM support for MPFS storage. In older 2.xx stack revisions, I2C EEPROM was supported by the XEEPROM.c file. This file has been renamed to I2CEEPROM.c. It is mutually exclusive with SPIEEPROM.c, and only one may be included in the project at a time. 14.Added new hardware definitions to Compiler.h. Pin mappings for the PICDEMNET and PIC18F97J60_TEST_BOARD boards have been added. FS_USB was also defined; however, it is untested and not recommended. See Compiler.h. The PIC18F97J60_TEST_BOARD is a non-production board that some Early Adopters of the PIC18F97J60 family parts have. 15.Changed type definitions for BYTE_VAL, WORD_VAL, DWORD_VAL, and moved the generic typedefs to GenericTypeDefs.h from StackTsk.h. This should improve compatibility with some future code libraries released by Microchip. 16.LCDBlocking.c module was modified to support 4-bit interfaces to LCD modules. The PICDEM.net board has the module wired using a 4-bit bus.

Fixes:

  1. Fixed a serious MAC TXBuffer leak in TCP.c. Previously TCP.c would allocate a buffer for each socket in use, but under heavy traffic conditions (ex: user holds down F5 on web browser), the buffer handle might have been discarded before releasing the buffer. As a result all TCP connections would have lost the ability to send any application data after the TXBuffer pool ran out.
  2. In the TCP_SYN_SENT TCP state, ACKs may only be received (as opposed to SYN+ACK packets) if the remote node thinks the connection is already open. A RST is now sent in response to an unexpected ACK, which may improve reconnection time when this (rare) condition occurs.
  3. A bug was present in the UDP module where remote MAC addresses would be cached for each socket, even when UDPInit() or UDPClose() was called, or the microcontroller was reset. As a result, responses to incoming packets could have been sent to the wrong MAC address. UDP Sockets are now properly initialized/closed.
  4. Fixed a potential timing bug in LCDBlocking.c. For lower values of CLOCK_FREQ, insufficient delay time was given to the LCD module, potentially causing improper operation.
  5. Changed PIC24F to default to the XT oscillator fuse rather than HS. The PIC24FJ128GA010 data sheet, rev. C reports that 8MHz should be used with XT mode, not HS mode like prior data sheets.
  6. Added a couple of wait states to the Realtek RTL8019AS MAC layer module for NICPut() and NICGet(). Previously, the PICmicro could not operate above approximately 25MHz without losing communication with the RTL8019AS chip.
  7. Updated PC based MPFS utility. When generating C files to be added to your MPLAB project, the include path to "Compiler.h" is now "..IncludeCompiler.h". The output file, ex: "MPFSImg.c" should be placed in the "Source" subfolder before compiling. For example, if you are in the main stack folder with the MPLAB projects, type: "mpfs /c WebPages SourceMPFSImg.c"
  8. IP Gleaning will now get properly disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled. The stack will still respond to ping requests which have the wrong destination IP address, but a correct MAC address. However, the stack will continue to keep its statically defined IP address when DHCP/IP Gleaning are disabled and the ping arrives.
  9. SPIEEPROM.c now saves and reconfigures the EEPROM_SPICON1 register (SSPCON1) before reading or writing to the SPI. After the read/write, it restores the saved state. This allows the SPI bus to operate at different speeds, depending on what peripheral is being accessed if other devices share the bus and can support different speeds. In particular, this fixes the SPI @ 10.4MHz problem on the PICDEM.net 2 board when using the ENC28J60.

Known Problems:

  1. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease is offline. The board will continue to use the expired IP address until the DHCP server comes back online, at which point the lease will be renewed or a new discovery will occur. A new discovery should occur after timing out, instead. It is believed that this problem has always existed in previous stack revisions.
  2. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease does not include Option 54, the Server Identifier. A new discovery should occur after timing out. It is believed that this problem has always existed in previous stack revisions.
  3. When an MPFS .c image file is added to a C30 project, a linking error reporting insufficient contiguous .const memory may occur when too much data is in the MPFS image (PSV window size limitation). Using the PSV window, 1 out of every 3 program memory bytes is wasted.
  4. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work.
  5. SNMP, TFTPc modules have not been tested with this version.
  6. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up).
  7. The C30 linker may misplace the __CONFIG2 section or disallow usage of MPFS images that are too big (add too much to the .const code section). The consequences of this are that the first configuration word at 0x157FC may not get set through code (must use the Configuration Bits dialog instead), and/or the project will not compile. This problem has been observed with C30 ver. 2.02 on the PIC24FJ128GA010 product. To work around this problem, the p24FJ128GA010.gld linker script has been modified. Specifically, line 68 has been commented out, which causes the linker to place all .text sections after placing all absolute sections. SSR 25966 in the C30 2.02 release notes may be related.
  8. It is observed with the Realtek RTL8019AS Ethernet controller and the demo AJAX web page which self refreshes rapidly, that occasional HTTP GET requests sent by the computer do not get received by the HTTP server. This is believed to be a RTL8019AS MAC layer bug. The TCP protocol handles the packet loss, but application performance suffers while waiting for the TCP retransmission. This problem is not observed with ENC28J60.c or ETH97J60.c MAC layers.
  9. The HI-TECH compiler version 9.50PL1 crashes when compiling LCDBlocking.c with 4 bit mode (PICDEMNET) and using a warning level of -3 or higher. To work around the problem, the HI TECH projects were set to use warning level -4.

Guiding Notes:

  1. To use the stack on a classic PICDEM.net demo board with the Realtek Ethernet controller, a PIC18F452 processor, and Microchip C18: -Use the C18EEPROM MPLAB project -Change the processor in the MPLAB IDE -Change linker script to "18f452i.lkr" in the MPLAB project. Use the one provided in the Linker subfolder, it has been modified to make more RAM available. -Update the hardware definitions macro. Click on Project -> Build Options... -> Project -> MPLAB C18 -> Add PICDEMNET, remove HPC_EXPLORER) -Remove ENC28J60.c from the project -Remove SPIEEPROM.c from the project -Add RTL8019AS.c to the project -Add I2CEEPROM.c to the project -Enable all compiler optimizations (Project -> Build Options... -> Project -> MPLAB C18 -> Categories Optimization -> Enable all)

******

v3.60 12 July 2006

******

General Information: This stack version is being publicly released, so the following changes are with respect to the prior public stack release (v3.02). Interim stack changes for version 3.16 and 3.50 are documented below for those using non-public releases, but can be ignored by most people.

Troubleshooting notes:

  1. If you have an Ethernet PICtail revision 2.1 and are having reliability issues when viewing the fast-refresh demo web page, you may need to install resistors in series with the ENC28J60 SI, nCS, and SCK pins. The recommended value is 100 to 200 ohms. This will reduce signal undershoot caused by long traces (parasitic inductance), which can violate the absolute maximum electrical specs and cause SPI data corruption. The HPC Explorer Rev 5 has fairly long traces to the PICtail connector.
  2. Enabling C30 2.02 compiler optimizations on the dsPIC33FJ256GP710, PIC24HJ256GP610 ES chips may produce unreliable code.
  3. When changing a C30 project to a PIC24H or dsPIC33F processor on the Explorer 16 demo board, the JTAG configuration fuse should be disabled to free the I/O pins associated with it. JTAG is enabled by default.
  4. This stack release was tested using MPLAB 7.40, C18 version 3.03, C30 version 2.02, and HI TECH PICC18 version 9.50PL1.
  5. When using the Ethernet PICtail board and HPC Explorer demo boards, make sure to plug the power into the Ethernet PICtail and not the HPC Explorer. The HPC Explorer's power regulator cannot provide enough current.

Changes:

  1. Source files have been split into separate directories. To compile old applications with this new stack, application source files may need to be updated to include the proper path to the stack header files.
  2. New MPLAB projects have been created: -C18EEPROM: Equivalent to the previously named "mpnicee" project. Designed for PIC18's using the C18 compiler. Web page content, board's IP address, MAC address, DHCP enabled state, etc. is stored in an external SPI EEPROM (25LC256 on demo boards). FTP Server demo is included. -C30EEPROM: New supporting PIC24 and dsPIC controllers using the C30 compiler. Similar to C18EEPROM. -C18ProgramMem: Equivalent to the previously named "mpnicpg" project. Web page content stored in internal FLASH program memory. Board's IP address, MAC address, DHCP enabled state, etc. is stored only in RAM and defaults are loaded from MY_DEFAULT_* constants in StackTsk.h. FTP Server demo is not included. Web pages cannot be updated remotely. -C30ProgramMem: New supporting PIC24 and dsPIC controllers using the C30 compiler. Similar to C18ProgramMem. -HTC18EEPROM: Equivalent to the previously named "htnicee" project. Designed for PIC18's using the HI TECH PICC18 compiler. Similar to C18EEPROM. -HTC18ProgramMem: Equivalent to the previously named "htnicpg" project. Designed for PIC18's using the HI TECH PICC18 compiler. Similar to C18ProgramMem.
  3. Created hardware definitions (pins, interrupt flags, special registers, etc) in Compiler.h for easy changing of hardware. Four demo board combinations are supported out-of-box now: -EXPLORER_16: Explorer 16 motherboard + Ethernet PICtail Plus daughter card. Tested with dsPIC33FJ256GP710, PIC24HJ256GP610, and PIC24F128GA010 ES PIMs. -HPC_EXPLORER: PICDEM HPC Explorer motherboard + Ethernet PICtail daughter card. Tested with PIC18F8722 onboard and PIC18F87J10 PIM. -DSPICDEM11: dsPICDEM 1.1 motherboard + Ethernet PICtail daughter card (manually air wired). See Compiler.h for proper pins to air wire. Tested with dsPIC30F6014A PIM. -PICDEMNET2: PICDEM.net 2 motherboard (PIC18F97J60) Change boards by changing the defined macro (Project -> Build Options... -> Project -> MPLAB Cxx -> Add macro). When moving to custom hardware, add an appropriate profile to Compiler.h. YOUR_BOARD is present as a placeholder.
  4. Added Ethernet PICtail Plus schematic (reference ENC28J60 daughter card design for Explorer 16 demo board). These boards have a Microchip part number of AC164123.
  5. Latest ENC28J60 rev. B5 errata workarounds added. The code checks the EREVID register and implements the appropriate workarounds as needed for the silicon revision, so rev. B1, B4, and B5 are all supported in this stack release.
  6. Significantly revised demonstration web page content in WebPages folder to use AJAX technology. Using asynchronous JavaScript code executing in the web browser, the status sections of the page are updated rapidly from the web server without doing a full page refresh. As a result, a virtually real time update of the potentiometer and button values can be displayed. Due to the constant use of new TCP sockets, multiple simultaneous users are not recommended. See the Index.cgi file for a simple static method of retrieving dynamic variables from the HTTP server.
  7. Changed IP Gleaning procedure. Now, if DHCP is enabled, the DHCP module will continue to look for a new IP address/renew existing IP address if the IP address is configured using IP Gleaning. Previously, the DHCP module would be disabled once a successful ICMP packet was received and used to configure the IP address.
  8. MAX_RETRY_COUNTS is 3 (previously it was 3, but an interim release changed it to 5).
  9. Updated TCP state machine. It now includes the TCP_FIN_WAIT_2 state. Some other changes were made to handle errors more robustly.

10.AN0String and AN1String now return all characters excluding the null terminator when the HTTP server calls HTTPGetVar (except when the string is 0 length). Previously, the null terminator was returned as well. 11.Dynamic pages (ie: .cgi files) are now served with an expired HTTP header to prevent browser caching and allow more dynamic content to be displayed. 12.Support for the HI TECH PICC18 compiler has changed. Special Function Register bits and other definitions have changed substantially from the previous HI TECH PICC18 projects in TCP/IP stack version 3.02 and earlier. The C18/C30 SFR and SFRbits naming conventions are now used and special remapping macros in Compiler.h are used to maintain a consistent syntax. The HI TECH PICC18 projects were tested with compiler version 9.50PL1 on the HPC Explorer board (PIC18F8722). 13.FTP client hash printing has been added to the FTP server. Now, whenever a chunk of data is successfully uploaded to the device, a '#' character will appear on the FTP client screen. The numbers of bytes each '#' represents is variable. 14.To improve maintainability, built in support for the "Compatible" A/D converter present on older PIC18 parts (ex: PIC18F452) has been removed. 15.Removed old LCD code originally provided for the PICDEM.net demo board. 16.Added LCDBlocking.c and LCDBlocking.h, which implement simple routines for writing to the LCD module on the Explorer 16 and PICDEM.net 2 development boards. The LCD on the dsPICDEM 1.1 board is not supported. The stack version and IP address are shown on the LCD on power up. 17.UART functions in MainDemo.c were replaced with C18 and C30 peripheral library functions. However, because the UART peripheral libraries are not being updated for newer silicon devices, the code was copied into UART.c and is compiled with the stack. 18.Multiple TX buffer support has been implemented. Most stack layers have been touched. ENC28J60.c has the most extensive changes. Each socket may use only one TX buffer. 19.Implemented TCP retransmission support regardless of if TCP_NO_WAIT_FOR_ACK is defined or not. 20.TCP_NO_WAIT_FOR_ACK in StackTsk.h has been undefined by default. This should increase default TCP connection robustness. Packets sent from the stack to the remote node will now be detected and retransmitted if lost or corrupted. 21.All TCP packets are now retransmitted immediately after being initially transmitted when TCP_NO_WAIT_FOR_ACK is undefined. This improves throughput greatly when communicating with systems which wait a long time before transmitting ACKs. TCP/IP stacks, such as that used by Microsoft Windows, implement the TCP Delayed Acknowledgement algorithm, which is why this retransmission is necessary for high performance. The double transmission feature can be disabled in the Microchip TCP/IP stack by defining "DEBUG" either in the TCP.c file or the project compiler macros section. Using DEBUG mode can be useful when trying to look for errors using Ethreal [ http://www.ethereal/ ]. 22.Lowered TCP_START_TIMEOUT_VAL from 60 seconds to 3 seconds. 60 seconds is an unreasonably long timeout for modern day network speeds. 23.Native support for the SLIP module has been dropped.

Fixes:

  1. A new IP address obtained via IP Gleaning will now update the LCD (if present), invoke the Announce module (for MCHPDetect.exe), and output the new address out the RS232 port.
  2. DHCP client will now correctly use the first DHCP offer received when connected to a network running multiple DHCP servers. Previously, the board would get no IP address when attached to a network with multiple DHCP servers (unless the DHCP request was transmitted before a second DHCP offer was received -- a relatively rare event). Additionally, DHCPLeaseTime does not get reset to 60 seconds or the value stored in the last DHCP packet received prior to receiving the ACK.
  3. UDPProces() will now correctly process received UDP packets that have a 0x0000 checksum field. The UDP protocol specifies that 0x0000 means the checksum is disabled. Packets with a 0x0000 checksum were previously thrown away unless the calculated checksum also happened to be 0x0000.
  4. The TCPIsPutReady() function will now honor the remote node's TCP window size. In other words, if the remote application pauses or cannot handle the incoming data rate, the TCP flow control feature will correctly function. Previously, if the remote node ran out of incoming buffer memory, the TCP layer would still allow more data to be transmitted. This would result in the loss or corruption of application data, with a potentially broken connection. The change requires 2 more bytes of RAM per TCP socket (TCB array).

Known Problems:

  1. On PICDEM.net 2 board ENC28J60 and 25LC256 EEPROM share the same SPI1 module. At 3.3V, the 25LC256 is only rated to 5MHz SPI clock, but the code is setting it to 10.4MHz because the MACInit() function reconfigures the same SPI1 module.
  2. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease is offline. The board will continue to use the expired IP address until the DHCP server comes back online, at which point the lease will be renewed or a new discovery will occur. A new discovery should occur after timing out, instead. It is believe that this problem has always existed in previous stack revisions.
  3. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease does not include Option 54, the Server Identifier. A new discovery should occur after timing out. It is believe that this problem has always existed in previous stack revisions.
  4. The MPFS utility has not been updated. When creating a .c image file, the include path for the Compiler.h file will be incorrect and need to be manually updated to "..IncludeCompiler.h".
  5. When an MPFS .c image file is added to a C30 project, a linking error reporting insufficient contiguous .const memory may occur when too much data is in the MPFS image (PSV window size limitation). Using the PSV window, 1 out of every 3 program memory bytes is wasted.
  6. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work.
  7. SNMP, TFTPc modules have not been tested with this version.
  8. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up).
  9. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled.

10.The C30 linker may misplace the __CONFIG2 section or disallow usage of MPFS images that are too big (add too much to the .const code section). The consequences of this are that the first configuration word at 0x157FC may not get set through code (must use the Configuration Bits dialog instead), and/or the project will not compile. This problem has been observed with C30 ver. 2.02 on the PIC24FJ128GA010 product. To work around this problem, the p24FJ128GA010.gld linker script has been modified. Specifically, line 68 has been commented out, which causes the linker to place all .text sections after placing all absolute sections. SSR 25966 in the C30 2.02 release notes may be related.

Guiding Notes:

  1. To change processors using a C18* project: -Change the processor in the MPLAB IDE -Change linker script (ex: 18f87j10i.lkr) in the MPLAB project. Use *i.lkr if the ICD2 is going to be used to debug with. -Update the hardware definitions in Compiler.h or change your demo board selection macro. (Project -> Build Options... -> Project -> MPLAB Cxx -> PICDEMNET2, etc)
  2. To change processors using a HTC18* project: -Change the processor in the MPLAB IDE -Update the hardware definitions in Compiler.h or change your demo board selection macro. (Project -> Build Options... -> Project -> MPLAB Cxx -> PICDEMNET2, etc)
  3. To change processors using a C30* project: -Change the processor in the MPLAB IDE -Change linker script (ex: p33FJ256GP710.gld) in the MPLAB project. -Update the hardware definitions in Compiler.h or change your demo board selection macro. (Project -> Build Options... -> Project -> MPLAB Cxx -> DSPICDEM11, etc) -Disable JTAG configuration fuse, if enabled
  4. When using the PICDEM.net 2 board, to write code targeting the PIC18F97J60 family Ethernet module: -Remove ENC28J60.c from the project -Add ETH97J60.c to the project -Plug the Ethernet cable into the left-most RJ45 jack (next to LCD)
  5. When using the PICDEM.net 2 board, to write code targeting the ENC28J60 Ethernet device: -Make sure ENC28J60.c is in the project -Make sure that ETH97J60.c is not in the project -Plug the Ethernet cable into the right-most RJ45 jack (next to board edge)
  6. When using the PICDEM.net 2 board, to write code targeting an Ethernet PICtail module (ENC28J60): -Make sure ENC28J60.c is in the project -Make sure that ETH97J60.c is not in the project -Make sure that the Ethernet PICtail J9 jumper is in the 2-3 position (default). -Properly update the hardware profile in Compiler.h. ENC_CS_TRIS and ENC_CS_IO need to be changed from D3 to B3. -Plug the Ethernet cable into the PICtail -Plug power into the PICDEM.net 2 board
  7. When using the Explorer 16 and Ethernet PICtail Plus demo boards, make sure to mate the PICtail to the motherboard using the topmost socket position, leaving the cable hanging over prototyping area. If SPI2 is desired, the PICtail should have the same orientation but be installed in the middle slot. Using SPI2, the hardware profile will need to be updated in Compiler.h.

******

v3.50 13 April 2006

******

Changes:

  1. Improved dsPIC33F and PIC24H support. UART functions are included now instead of precompiled object files for the PIC24F. The 12-bit A/D converter is now shown in use on the demo web content. When changing a C30 project to a PIC24H or dsPIC33F processor on the Explorer 16 demo board, the JTAG configuration fuse should be disabled to free the I/O pins associated with it. JTAG is enabled by default.
  2. Added LCDBlocking.c and LCDBlocking.h, which implement simple routines for writing to the LCD module on the Explorer 16 development board. The stack version and IP address are shown on the LCD on power up.
  3. Added "C18ProgramMem" and "C30ProgramMem" MPLAB projects for MPFS storage (web page content) on on-chip program memory. These projects are equivalent to the previously named "mpnicpg" project in prior stack releases.
  4. Multiple TX buffer support has been implemented. Most stack layers have been touched. ENC28J60.c has the most extensive changes. Each socket may use only one TX buffer.
  5. Implemented TCP retransmission support when TCP_NO_WAIT_FOR_ACK is undefined.
  6. TCP_NO_WAIT_FOR_ACK in StackTsk.h has been undefined by default. This should increase default TCP connection robustness.
  7. All TCP packets are now retransmitted immediately after being initially transmitted when TCP_NO_WAIT_FOR_ACK is undefined. This improves throughput greatly when communicating with systems which wait a long time before transmitting ACKs.
  8. Lowered TCP_START_TIMEOUT_VAL from 60 seconds to 3 seconds.
  9. Increased MAX_RETRY_COUNTS from 3 to 5 times.
  10. The example HTTP server now returns a content expiration date which has already past. This prevents web browser caching and allows more dynamic content to be displayed.
  11. Added WebPages_JScript folder, with new web pages that support dynamic page updates without a full page reload. A tiny page of dynamic variables is returned by the web server and Javascript executing on the target web browser changes DOM elements as needed. Button S5 (RA7) on the Explorer 16 demo board and S1 (RB0) on the HPC Explorer demo board changes the page color scheme. The rapid dynamic updates do not work on some web browsers (Internet Explorer works, Firefox does not).

Known Problems:

  1. MPFS utility has not been updated. When creating a .c image file, the include path for the compiler.h file will be incorrect and need to be manually updated.
  2. When an MPFS .c image file is added to a C30 project, a linking error reporting insufficient contiguous .const memory may occur (PSV window size limitation).
  3. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work.
  4. SNMP, TFTPc, SLIP modules have not been tested with this version.
  5. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up).
  6. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled.
  7. The IP address being outputted out the RS232 port and through the Announce module does not happen when the IP address is configured using IP Gleaning.
  8. On the PIC24F with C30 compiler optimizations enabled (such as Option 3, maximum speed), the project may not work. The PIC24F headers that come with C30 ver. 2.01 declare several SFRs without using the volatile keyword.
  9. dsPIC30 support is incomplete. Currently PIC18, PIC24F, PIC24H, and dsPIC33F processors are supported.

******

v3.16.00: 06 March 2006

******

Changes:

  1. Added unified support for both the Microchip C18 and C30 compilers. The intention is to allow one code base to be compiled for any PIC18, PIC24F/H, dsPIC30, or dsPIC33 product (with adequate memory). See the "Tested Using" section for what is known to work.
  2. To improve maintainability, support for the HI-TECH PICC18 compiler has been dropped.
  3. New project workspaces have been created, "C30EEPROM.mcw" and "C18EEPROM.mcw". C18EEPROM.mcw is equivalent to the previously named "mpnicee.mcw." C30EEPROM is intended to be used for PIC24 and dsPIC 16-bit controllers.
  4. Source files have been split into separate directories.
  5. Latest ENC28J60 rev. B5 errata workarounds added. The code checks the EREVID register and implements the appropriate workarounds as needed for the silicon revision, so rev. B1, B4, and B5 are all supported in this stack release.
  6. Removed old LCD code originally provided for the PICDEM.net demo board.
  7. To improve maintainability, built in support for the "Compatable" A/D converter present on older PIC18 parts (ex: PIC18F452) has been removed.
  8. UART functions in MainDemo.c were replaced with C18 and C30 peripheral library functions.

Tested Using:

  1. Software: -MPLAB version 7.31.01 -C18 version 3.02 -C30 version 2.01
  2. Hardware: -PICDEM HPC Explorer rev. 4 (PIC18F8722) + Ethernet PICtail Daughter Board (ENC28J60

B1) -Explorer 16 rev. 4 (PIC24FJ128GA010 ES and dsPIC33FJ256GP710 ES) + Ethernet PICtail+ Daughter card (ENC28J60 B1).

  3. Notes: -MPLAB 7.31.01 is a development build. The publicly available version 7.31 should work fine, with the exception of being unable to program dsPIC33 and PIC24H parts with the ICD 2. -No dsPIC30 or PIC24H parts have been tested yet.

Known Problems:

  1. MPFS utility has not been updated. When creating a .c image file, the include path for the compiler.h file will be incorrect and need to be manually updated.
  2. When an MPFS .c image file is added to a C30 project, a linking error reporting insufficient contiguous .const memory may occur.
  3. On the PIC24FJ128GA010, it is observed that some inbound packets are lost from time to time with no anticipated reason.
  4. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work.
  5. SNMP, TFTPc, SLIP modules have not been tested with this version.
  6. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up).
  7. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled.
  8. The IP address being outputted out the RS232 port and through the Announce module does not happen when the IP address is configured using IP Gleaning.
  9. Multiple TX buffer support is not fully inplemented in the MAC layer, ENC28J60.c. Stack behavior when TCP_NO_WAIT_FOR_ACK is undefined may be unexpected.

******

v3.02.00: 20 Feb 2006

******

Fixes:

  1. Changed TXSTART in ENC28J60.c to stop wasting a byte.
  2. Changed RXSTOP in ENC28J60.c to always be an odd value to properly implement an ENC28J60 silicon errata workaround.
  3. Changed initialization of ERXRDPT in MACInit() to agree with the current errata.

Changes:

  1. Licence agreement
  2. Schematics and other board files to the Ethernet PICtail Daughter Board have been updated to revision 5. Of significant note, the nRESET pin has been freed and 200 ohm resistors were added to the ENC28J60 SI, nCS, and SCK pins. The added resistors reduce undershoot caused by stray trace inductance and strong host output drivers.

Known Problems:

  1. Testing on the PICDEM.net demo board with the Realtek RTL8019AS Ethernet controller has not been done. Moving to the HPC Explorer demo board has resulted in pinout and other hardware changes.
  2. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work.
  3. SNMP, TFTPc, LCD, SLIP modules have not been tested with this version.
  4. The stack may behave incorrectly if compiled using the Hitech compiler with a high optimizations setting.
  5. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up).
  6. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled.
  7. The IP address being outputted out the RS232 port and through the Announce module does not happen when the IP address is configured using IP Gleaning.
  8. Multiple TX buffer support is not fully inplemented in the MAC layer, ENC28J60.c. Stack behavior when TCP_NO_WAIT_FOR_ACK is undefined may be unexpected.

******

v3.01.00: 18 Jan 2006

******

Fixes:

  1. Implemented latest ENC28J60 silicon errata workarounds.
  2. Fixed a bug in TCP.c and UDP.c which would incorrectly write the packet checksum into the RX buffer incorrectly when the checksum field was exactly spanning the RX wrapparound boundary in the ENC28J60. This problem would have caused packets to be discarded in rare circumstances

Known Problems:

  1. Testing on the PICDEM.net demo board with the Realtek RTL8019AS Ethernet controller has not been done. Moving to the HPC Explorer demo board has resulted in pinout and other hardware changes.
  2. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work.
  3. SNMP, TFTPc, LCD, SLIP modules have not been tested with this version.
  4. The stack may behave incorrectly if compiled using the Hitech compiler with a high optimizations setting.
  5. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up).
  6. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled.
  7. The IP address being outputted out the RS232 port and through the Announce module does not happen when the IP address is configured using IP Gleaning.
  8. Multiple TX buffer support is not fully inplemented in the MAC layer, ENC28J60.c. Stack behavior when TCP_NO_WAIT_FOR_ACK is defined may be unexpected.

******

v3.00.00: 16 Jan 2006

******

Changes:

  1. The stack now targets the PICDEM HPC Explorer demo board (PIC18F8722 MCU) with an attached Ethernet PICtail Daughter Board (with the Microchip ENC28J60 Ethernet controller).
  2. IP Gleaning is no longer enabled (STACK_USE_IP_GLEANING is not defined) by any of the default project files.
  3. The IP address, whenever it changes, is outputted out the RS232 serial port in human readable form. Any terminal program, such as HyperTerminal can be used to read it. This allows the IP address to be easily determined when DHCP is used. The serial port defaults to 19200 baud when CLOCK_FREQ in Compiler.h is properly defined.

Additions:

  1. Microchip ENC28J60 Ethernet controller support. Support is included through the ENC28J60.c and ENC28J60.h files. Various other files were modified to take advantage of ENC28J60 specific features, like the hardware DMA/IP checksum engine. This new MAC driver incorporates several new functions which can be called from any layer above the MAC. The functions are: MACSetDuplex() MACPowerDown() MACPowerUp() MACSetPMFilter() MACDisablePMFilter() CalcIPBufferChecksum() MACCalcRxChecksum() MACCalcTxChecksum() MACCopyRxToTx() See the ENC28J60.c file comments for function descriptions. The ENC28J60.c file also incroporates TestMemory() which can do a power on self test of various hardware functions. TestMemory() is included and used when MAC_POWER_ON_TEST is defined in StackTsk.h. It is undefined by default. Defining it will require some program memory.
  2. Announce module. Announce.c and announce.h have been added. When included in the project, STACK_USE_ANNOUNCE must be defined. This module will broadcast a UDP message to port 30303 containing the local MAC address whenever the local IP address changes. This addition is intended to facilitate device discovery on DHCP enabled networks and eliminate the need for an RS232 connection if board reconfiguration is not needed. To retrieve the UDP message on your computer, use the new MCHPDetect.exe program included in the MCHPDetect subfolder.
  3. The spieeprom.c file was added to support SPI EEPROM chips for MPFS storage. ENC28J60.c and spieeprom.c may both be included and they will share the same SPI module.

Improvements:

  1. Renamed files/edited files so that the HI-TECH compiler won't raise messages stating that include files were spelled wrong.
  2. Moved MAX_ICMP_DATA_LEN from StackTsk.c to ICMP.h file for easier maintenance.
  3. Corrected STACK_USE_SIIP typo in dhcp.c file - Thanks to Gisle J.B.
  4. Implemented UDP checksum logic in UDPProcess() in UDP.c file.
  5. Renamed CalcTCPChecksum() in tcp.c file to CalcIPBufferChecksum().
  6. Moved CalcIPBufferChecksum() to helpers.c to reuse it for UDP checksum calculation.
  7. Modified UDPProcess() in UDP.c and TCPProcess() in TCP.c to include localIP as third new parameter. This makes pseudo header checksum calculation correct in both functions. StackTsk.h, UDP.h and TCP.h files were also modified to reflect these changes.
  8. Modified TCP.C file to include compile-time check of STACK_USE_TCP define. If it is not defined, an error will be displayed.
  9. Removed an unnecessary call to MACDiscardRx() when an IP packet is received but fails version, options length, or header checksum tests.
  10. Changed LCD code to be compile time removable by undefining USE_LCD.

Fixes:

  1. IPHeaderLen in IP.c is initialized properly now when IPGetHeader() is called.
  2. Under some circumstances, HandleTCPSeg() would acknowlege, but throw valid received TCP packets away, resulting in loss of application data. An invalid comparison in HandleTCPSeg() has been fixed to prevent this situation from occuring. *** Thanks go to Richard Shelquist for identifying this problem.
  3. Fixed StackTsk.c file so that if a static IP address is used and the LINK is removed, the node IP address is not cleared.
  4. Invalid ICMP echo replies are no longer generated for echo requests with a data length of 33 (one more than the configured maximum).
  5. Changed MAX_OPTIONS_LEN from 20 to 40. The maximum IP options length is now in agreement with the IP RFC.
  6. Changed IPSetRxBuffer() from a macro to a function. The function takes into account any options which may be present in the header of received IP packets. Previously, possible options were not taken into account when calculating the offset.

Known Problems:

  1. Testing on the PICDEM.net demo board with the Realtek RTL8019AS Ethernet controller has not been done. Moving to the HPC Explorer demo board has resulted in pinout and other hardware changes.
  2. Sometimes when the FTP sever is used, an attempt to put a file is unsuccessful. The problem may be caused when an HTTP request to GET a file is made at the wrong time.
  3. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work.
  4. SNMP, TFTPc, LCD, SLIP modules have not been tested with this version.
  5. The stack may behave incorrectly if compiled using the Hitech compiler with a high optimizations setting.
  6. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up).
  7. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled.
  8. The IP address being outputted out the RS232 port and through the Announce module does not happen when the IP address is configured using IP Gleaning.
  9. Multiple TX buffer support is not fully inplemented in the MAC layer, ENC28J60.c. Stack behavior when TCP_NO_WAIT_FOR_ACK is defined may be unexpected.

******

v2.20.04.01: 9/24/03

******
  1. Recreated MPLAB projects to avoid problems when source is not at MCHPStack location.

******

v2.20.04: 9/5/03

******

Fixes:

  1. Modified DHCPReset() in DHCP.c to not reset DHCP state machine if it was previously disabled using DHCPDisable(). This would make sure that if DHCP module was enabled and application had run-time disabled DHCP and network cable is disconnected, stack will not clear its IP address.

  2. Rebuilt mib2bib.exe file with static library options. This fixes problem where one tries to execute this exe, an error occurs about missing DLLs.

******

v2.20.03:

******

Improvements:

  1. When DHCP is enabled, LINK is monitored and IP address is reset on disconnect. New IP configuration is obtained on LINK reconnect. - For RealTek only. Modified DHCP.c to add DHCPReset() Modified MAC.c to add MACIsLinked() Modified StackTsk.h to add BYTE_VAL def.

Changes:

  1. Modified SMSC91c111.c to add empty MACIsLinked() - will be populated in next rev.

Bug Fixes:

  1. Corrected DHCP logic to accept first DHCP offer instead of second response.
  2. Corrected DHCP logic to check for chaddr in DHCP offer and accept one that matches with local MAC address. This will fix problem where if multiple nodes were on bus and all requested DHCP address, all would accept response from one server instead of verifying who was intended node.
  3. Fixed UDPClose() in UDP.c to use INVALID_UDP_PORT instead of INVALID_UDP_SOCKET because of which a closed socket would not be scanned correctly.
  4. Modified UDP.h to use long contsant designators for INVALID_UDP_OPRT to explicitly state that it is a long.

******

v2.20.02:

******

Beta version containing TFTP client module.

Addition:

  1. TFTP Client module - See TFTPc.* and TFTPcDemo.c for more information. See MpTFTPcDemo and HtTFTPcDemo projects for build information.

Bug Fix:

  1. UDPIsGetReady() was modified to overcome compiler rule where only 8-bit value was used to evaluate non-zero condition.
  2. ARPResolve() in ARPTsk was fixed to clear Cache.IPAddr value.

******

v2.20.01:

******

Bug fix:

  1. Fixed SMSC91C111.c where MACInit() would hand if ethernet link is not detected.

******

v2.20:

******

Bug Fixes:

  1. General - Removed most of harmless warnings.
  2. C18Cfg.asm - Fixed "include" instead of "define".
  3. DHCP.c - Increased DHCP_TIMEOUT_VAL to 2 seconds. Fixed problem where UDP active socket was not set before calling UDP

functions in SM_DHCP_BROADCAST state.

  4. MAC.c - Fixed MACIsTxReady() where under heavy traffic it would always return

FALSE. This fixes bug where all high level applications would stop transmitting.

  5. TCP.c - Enabled portion of code that performs timeout logic even if

TCP_NO_WAIT_ACK is defined. This fixes bug where occasionally, tcp applications such as HTTP server would stop working after few hours.

  6. UDP.c - Fixed UDPGet() where it would return FALSE on last good byte. Fixed UDPProcess() where it was calculating incorrect length.

Added bFirstRead flag with UDP sockets similar to TCP sockets so that whenever first UDP byte is read, MAC read pointer will be reset to begining of correct packet. This change fixes problem where if one transmits a packet while UDP packet is pending in a socket, next get to pending UDP socket would return wrong data. (This is apparent only when there is heavy network traffic)

Known Issues:

  1. HiTech v8.20 PL4 with all optimization enabled may not work properly.
  2. C18 "Static" and "Auto" mode may not be used - there are too many local variables to

fit in standard stack of 256 bytes. One may modify linker script file to avoid this limitation.

Improvements:

  1. Modified TICK def. in Tick.h to unsigned long to support 32-bit wide SNMP tick.
  2. Added SNMP Module (SNMP.c)
  3. Added Two new demo projects - DemoSNMPApp and HtDemoSNMPApp.
  4. Created MPLAB 6.X projects for different demo configurations.
  5. MAC.c - Added MACGetTxOffset().
  6. MPFS.c - Added MPFSSeek(), MPFSTell().
  7. MPFSImg.*- Rebuilt to reflect v2.20, footprint changes etc.
  8. StackTsk.h- Enhanced WORD_VAL, DWORD_VAL defs. Added STACK_USE_SNMP and related compile-time checks.
  9. UDP.h - Added UDPSetTx and UDPSetRx macros. Moved UDP_SOCKET_INFO structure to header file.
  10. WebSrvr.c- Modifed MCHPStack version message and added DATE info to BoardSetup menu.
  11. Added support for SMSC LAN91C111 10/100 Non-PCI ethernet controller Use "SMSC91C111.C" instead of MAC.c. "mpnicee_smsc" is a sample project that uses PIC18F8720 and SMSC NIC. "MasterDemo.c" is a main source file for above project that includes all modules - must use device with more than 32KB of memory.

******

v2.11:

******

Bug Fixes:

  1. Fixed dhcp.c to make it work with new C18 startup code.

Improvements:

  1. Modified websrvr.c DownloadMPFS() to make use of compiler allocated XMODEM data block rather than use fixed address block starting at 0x400.

******

v2.10: 7/9/02

******

Bug Fixes:

  1. Fixed HTTP Server bug where a form submission with empty parameter value would not parse correctly.

******

v2.0: 5/22/02

******

******

New Modules:

******
  1. Added UDP, DHCP, FTP and IP Gleaning
  2. Added PICDEM.net LCD support
  3. Added board setup through RS-232.

******

Improvements:

******
  1. Optimized serial EEPROM access routines in terms of speed and size (Replaced ee256.* files with eeprom*.h)
  2. Improved board setup through RS-232.

******

Known Issues:

******
  1. LCD may not display properly on MCLR only. Workaround: 1. Debug XLCDInit() routine in "xlcdlh"
    2. Always do POR reset.

  2. SLIP connection is not very robust. Workaround: None at this time.

  3. Hi-Tech Compiler:
    1. Aggressive optimization breaks the functionality. Workaround: Apply optimization listed in each source file comment

header.

  2. In order to use V8.12, you will need to remove "FTP Server" from

Ht*.pjt. You will also need to disable all optimizations.

  4. C18 Compler: 1. Static model does not compile. Workaround: None at this time.
    2. Overlay model breaks the functionality. Workaround: None at this time.
    3. All modules does not fit in 32KB memory. Workaround: 1. None at this time.
      2. Sample project disables some modules.

******

New Files:

******

======================================================================================== ==================================== File Purpose ======================================================================================== ====================================

  1. delay.* Provides CLOCK_FREQ depenent delay routines.
  2. dhcp.* DHCP client support
  3. ftp.* FTP server
  4. udp.* UDP socket support
  5. xeeprom.* Improved ee256.* and renamed.
  6. xlcd.* External LCD support.
  7. version.log To track changes and history.

******

Changes:

******

======================================================================================== ==================================== File Change To-do for v1.0 stack applications ======================================================================================== ====================================

  1. arptsk.c 1. Fixed STACK_CLIENT_MODE compile errors.

None

  2. Modifed ARPIsResolved() to support IP Gleaning

None

  2. c18cfg.asm 1. Added PIC18F452 configuration

None

  2. Fixed "include" errors.

None

  3. compiler.h 1. Included "stdlib.h" in both C18 and Hi-Tech compilers.

None

  2. Moved CLOCK_FREQ from "stacktsk.h" to this file.

None

  3. Added PORTA defs.

None

  4. htnicee.pjt 1. Removed "ee256.c".

None

  2. Added "udp.c", "dhcp.c", "ftp.c", "xlcd.c", "xeeprom.c" files

Add these files if needed.

  5. htnicpg.pjt None

  6. htslee.pjt 1. Removed "ee256.c".

None

  2. Added "ftp.c", "xlcd.c", "xeeprom.c" files

None

  7. http.c 1. Included compile-time verification that HTTP module is included.

None

  2. Put HTTP message strings into one array "HTTPMessages".

None

  3. Modified to return "Service Unavailable" message if MPFS is being

None remotely programmed.

  4. Modified SendFile() to make use of sequential EEPROM read.

None

  8. ip.c 1. Added one more paramter to IPGetHeader() to support IP Gleaning

Custom apps using IP needs to be

modified.

  9. mac.c 1. Replaced fixed delay routines with CLOCK_FREQ dependent

None routines

  10. mpfs.c 1. Replaced ee256.h with xeeprom.h.

None

  2. Added MPFSFormat(), MPFSPut() etc. routines

None

  3. Added sequential read and page write operations

Custom apps using MPFS directly

needs to be modified.

  4. Defined MPFS_WRITE_PAGE_SIZE for MPFSPut operations.

Apps using different EEPROM page size

needs to be modified.

  11. mpnicee.pjt 1. Removed "ee256.c"

None

  2. Added "xcld.c", "xeeprom.c" files

None

  12. stacktsk.c 1. Replaced ee256.h with xeeprom.h

None

  2. Added IP Gleaning and DHCP support.

None

  13. stacktsk.h 1. Moved CLOCK_FREQ to compiler.h

None

  2. Added STACK_USE_DHCP, STACK_USE_FTP_SERVER etc. options

None

  3. Added compile-time enable/disable of modules based on selection of higher level modules.

None

  4. Modified MY_DEFAULT_MAC_BYTE? to use Microchip OUI id.

None

  5. Added compiler-time check to confirm available TCP sockets

None

  6. Added MSB and LSB macros.

None

  7. Added SerialNumber etc. to AppConfig structure

None

  8. Commented module selection defines: They are defined by cmopiler

None command-line options. Real application should define them here in this file.

  14. tcp.c 1. Moved TCP_STATE and TCP_INFO to .h file.

None

  2. Fixed TCPIsConnected()

None

  3. Fixed TCPDisconnect()

None

  4. Modified TransmitTCP() to set receive window of one segment

None

  5. Modified TransmitTCP() to use max segment size equal to predefined value.

None

  6. Improved TCP State machine

None

  15. tick.c 1. Modified TICK type to 16-bit.

None

  2. Made use of TICK_PRESCALE_VALUE

None

  3. Added code to blink PICDEM.net "System LED"

Remove if not required.

  16. websrvr.c 1. Added LCD support

N/A

  2. Made TickUpdate() on Timer0 interrupt

N/A

  3. Added code to save/restore board configuration

N/A

  4. Added board setup via RS-232.

N/A

  5. Added call to FTP modules

If needed, add this.

Topics
Name | Description
Stack Performance | Latest stack performance measurements using TCPPerformanceTest.c and UDPPerformanceTest.c test modules.
Memory Usage | Details stack program and data memory requirements.
Peripheral Usage | Describes the peripherals required by the TCP/IP stack.
Release Notes


Stack Performance

Contents | Index | Home
Previous | Up | Next
Stack Performance

Note that this table will not appear in the PDF version of the help file; see the "TCPIP Stack Performance.htm" file in the TCPIP documentation folder in the Microchip Application Library help folder.

Stack and Compiler Versions |  |  |  |  |  |  |  |  |  |  |  |  |  |
TCP/IP Stack v5.36.2 |  |
MPLAB C Compiler for PIC18 MCUs (C18) v3.38 |  |  |
MPLAB C Compiler for PIC24 MCUs and dsPIC DSCs (C30) v3.25 |  |  |  |
MPLAB C Compiler for PIC32 MCUs (C32) v1.12 |  |  |
Wired test setup: Connect the board under test directly to a computer using a crossover cable. Follow the TCPIP Stack Help file's instructions for the TCP/UDP Performance Test. |  |  |  |  |  |  |  |  |  |  |  |  |  |
Wireless test setup: Connect the PC to a router with a Category 5 cable. Connect the demo board to the router wirelessly Follow the TCPIP Stack Help file's instructions for the TCP/UDP Performance Test.
Microcontroller | MIPS | Network Controller | Interface | LAN Transmit Throughput (Kbytes/sec) |  |  |  | Internet Transmit Throughput at 100ms ping (estimated Kbytes/sec)(1) |  |  |  | Compiler | Optimization | Test Boards
 |  |  |  | TCP with 200 byte TX FIFO | TCP with 2000 byte TX FIFO | TCP with 8000 byte TX FIFO | UDP | TCP with 200 byte TX FIFO | TCP with 2000 byte TX FIFO | TCP with 8000 byte TX FIFO | UDP
PIC18F97J60 | 10.4 | Internal 10BaseT | - | 34 | 76 | N/A | 113 | 2 | 20 | N/A | 113 | C18 | Debug | PICDEM.net 2
PIC18F8722 | 10 | ENC28J60 | SPI, 10 MHz | 21 | 45 | N/A | 63 | 2 | 20 | N/A | 63 | C18 | Debug | PIC18 Explorer, Ethernet PICtail
PIC24FJ128GA010 | 16 | ENC28J60 | SPI, 8 MHz | 56 | 136 | N/A | 203 | 2 | 20 | N/A | 203 | C30 | s (min size) | Explorer 16, Ethernet PICtail Plus
dsPIC33FJ256GP710(2) | 40 | ENC28J60 | SPI, 8 MHz | 75 | 200 | N/A | 258 | 2 | 20 | N/A | 258 | C30 | s (min size) | Explorer 16, Ethernet PICtail Plus
PIC32MX360F512L | 80 | ENC28J60 | SPI, 20 MHz | 110 | 347 | N/A | 461 | 2 | 20 | N/A | 461 | C32 | s (min size) | Explorer 16, Ethernet PICtail Plus
PIC32MX795F512L | 80 | ENC28J60 | SPI, 20 MHz | 115 | 363 | N/A | 456 | 2 | 20 | N/A | 456 | C32 | s (min size) | Explorer 16, Ethernet PICtail Plus
PIC18F8722 | 10 | ENC624J600(3) | SPI, 10 MHz | 28 | 76 | 80 | 114 | 2 | 20 | 80 | 114 | C18 | Debug | PIC18 Explorer, Fast 100Mbps Ethernet PICtail Plus
PIC24FJ128GA010 | 16 | ENC624J600(3) | SPI, 8 MHz | 57 | 168 | 183 | 362 | 2 | 20 | 80 | 362 | C30 | s (min size) | Explorer 16, Fast 100Mbps Ethernet PICtail Plus
dsPIC33FJ256GP710(2) | 40 | ENC624J600(3) | SPI, 8 MHz | 94 | 291 | 321 | 554 | 2 | 20 | 80 | 554 | C30 | s (min size) | Explorer 16, Fast 100Mbps Ethernet PICtail Plus
PIC32MX360F512L | 80 | ENC624J600(3) | SPI, 13.33 MHz | 142 | 374 | 421 | 692 | 2 | 20 | 80 | 692 | C32 | s (min size) | Explorer 16, Fast 100Mbps Ethernet PICtail Plus
PIC32MX795F512L | 80 | ENC624J600(3) | SPI, 13.33 MHz | 154 | 412 | 469 | 784 | 2 | 20 | 80 | 784 | C32 | s (min size) | Explorer 16, Fast 100Mbps Ethernet PICtail Plus
PIC24FJ128GA010 | 16 | ENC624J600(3) | PSP Mode 5, PMP | 101 | 321 | 363 | 1028 | 2 | 20 | 80 | 1028 | C30 | s (min size) | Explorer 16, Fast 100Mbps Ethernet PICtail Plus
dsPIC33FJ256GP710(2) | 40 | ENC624J600(3) | PSP Mode 5, Bitbang | 202 | 711 | 868 | 2038 | 2 | 20 | 80 | 2038 | C30 | s (min size) | Explorer 16, Fast 100Mbps Ethernet PICtail Plus
PIC32MX360F512L | 80 | ENC624J600(3) | PSP Mode 5, PMP | 200 | 833 | 1027 | 2071 | 2 | 20 | 80 | 2071 | C32 | s (min size) | Explorer 16, Fast 100Mbps Ethernet PICtail Plus
PIC32MX795F512L(3) | 80 | Internal 100BaseTX | - | 393 | 1635 | 2543 | 8449 | 2 | 20 | 80 | 8449 | C32 | s (min size) | PIC32 Ethernet Starter Kit
PIC18F97J60 | 10.4 | MRF24WB0M | SPI, 10.4 MHz | 5 | 23 | 30 | 40 | 2 | 20 | 30 | 40 | C18 | Debug | PICDEM.net 2, MRF24WB0MA Wi-Fi PICtail Plus
PIC24FJ256GB110 | 16 | MRF24WB0M | SPI, 8 MHz | 8 | 43 | 63 | 48 | 2 | 20 | 63 | 48 | C30 | s (min size) | Explorer 16, MRF24WB0MA Wi-Fi PICtail Plus
dsPIC33FJ256GP710(2) | 40 | MRF24WB0M | SPI, 8 MHz | 8 | 45 | 74 | 48 | 2 | 20 | 74 | 48 | C30 | s (min size) | Explorer 16, MRF24WB0MA Wi-Fi PICtail Plus
PIC32MX360F512L | 80 | MRF24WB0M | SPI, 20 MHz | 9 | 51 | 83 | 48 | 2 | 20 | 80 | 48 | C32 | s (min size) | Explorer 16, MRF24WB0MA Wi-Fi PICtail Plus
PIC32MX795F512L | 80 | MRF24WB0M | SPI, 20 MHz | 9 | 53 | 84 | 44 | 2 | 20 | 80 | 44 | C32 | s (min size) | Explorer 16, MRF24WB0MA Wi-Fi PICtail Plus
1. Internet throughput with acknowledged protocols, such as TCP, are capped by the formula (Buffer Size)/(Ping Time). Assuming round trip acknowledgement latency cannot be controlled, bigger buffers must be used to increase throughput. Internet performance is derived from LAN throughput and is not measured. |  |  |  |  |  |  |  |
2. Stack performance with a dsPIC33F is identical to a PIC24H device at the same processor clock. No DSP features are used by the TCP/IP stack. |  |  |  |  |  |  |  |
3. ENC624J600 and PIC32MX7XX/6XX Internal 100BaseTX Ethernet measurements are done in 100Mbps, full duplex mode. |  |  |  |  |  |  |  |

Release Notes > Stack Performance


Memory Usage

Contents | Index | Home
Previous | Up | Next
Memory Usage

These tables contain the PIC program and data memory requirements for the TCP/IP stack. The first two rows list the program memory consumption of the stack's required files, and each additional row contains the additional memory required to implement specific modules. These values are approximations; the program memory size may increase depending on application code, or decrease based on optimizations of modules with overlapping code. Modules that require user-implemented API functions (SNMP, HTTP) are tested without additional code. The global data memory column includes only the RAM needed for the required structures in the stack; it does not include the memory used for socket allocation.

The C18 code uses the PIC18F97J60 family Ethernet controller as the MAC/PHY chip; the C30 and C32 measurements are made using the ENC28J60 Ethernet controller (ENCX24J600 sizes are similar). All compilers include a separate Required Stack Code line for Wi-Fi applications using the MRF24WB0M as the network controller. These two Required Stack Code lines are mutually exclusive -- do not add them together. Instead, chose the line representing your network controller.

These values are approximations obtained from TCP/IP Stack version 5.31. Note that these tables will not appear in the PDF version of the help file; see the "TCPIP Cxx Memory Usage.htm" files in the TCPIP documentation folder in the Microchip Application Library help folder.

C18

Module | Program Memory (bytes) No Optimizations | Program Memory (bytes) All Optimizations | Global Data Memory (bytes)
Required Stack Code - PIC18F97J60 family controller | 9118 | 7568 | 585
Required Stack Code - MRF24WB0M Wi-Fi controller | 25482 | 19498 | 1078
Announce(1) | +3395 | +2775 | +188
AutoIP | +2860 | +2090 | +88
DHCP Client(1) | +6244 | +4684 | +241
DHCP Server(1) | +5012 | +3490 | +198
DNS Client(1) | +5955 | +4333 | +243
Dynamic DNS Client(1,2,3) | +31519 | +22039 | +677
HTTP2 Server/MPFS2(2) | +38433 | +25137 | +646
ICMP Client | +1529 | +1263 | +42
ICMP Server | +436 | +410 | +4
NBNS(1) | +4465 | +3589 | +208
SMTP Client(1,2,3) | +33311 | +23485 | +666
SNMP Agent(1,4) | +27837 | +18485 | +733
SNTP Client(1,3) | +7269 | +5287 | +267
SSL Client | +50139 | +35221 | +1818
SSL Server | +51757 | +36547 | +1464
SSL Server/Client | +59279 | +41027 | +1939
TCP | +19028 | +13370 | +323
UDP | +2730 | +2270 | +186
Total(5) | 97947 | 67339 | 2573
Total + SSL(5) | N/A(6) | N/A(6) | N/A(6)
Notes: |  |  |
(1): Code size includes the UDP module (required for operation). |  |  |
(2): Code size includes the TCP module (required for operation). |  |  |
(3): Code size includes the DNS module (required for operation). |  |  |
(4): Code size includes the MPFS2 module (required for operation). |  |  |
(5): Total includes the required files, and the ARP, AutoIP, DHCP Client and Server, DNS, |  |  |
Dynamic DNS, HTTP2, ICMP, MPFS2, NBNS, SMTP, SNMP, SNTP, TCP, and UDP modules. |  |  |
(6): Compiled code size exceeds the capacity of the target processor. |  |  |

C30

Module | Program Memory (bytes) Size Optimization (-0s) | Program Memory (bytes) Speed Optimization (-03) | Global Data Memory (bytes)
Required Stack Code - ENC28J60 network controller | 8244 | 23451 | 150
Required Stack Code - MRF24WB0M Wi-Fi controller | 15147 | 25356 | 308
Announce(1) | +1809 | +2061 | +146
AutoIP | +2220 | +2307 | +58
DHCP Client(1) | +4395 | +4965 | +188
DHCP Server(1) | +3090 | +3873 | +152
DNS Client(1) | +3840 | +4725 | +182
Dynamic DNS Client(1,2,3) | +15675 | +23982 | +474
HTTP2 Server/MPFS2(2) | +18780 | +30114 | +534
ICMP Client | +1356 | +1449 | +30
ICMP Server | +348 | +375 | +0
NBNS(1) | +2844 | +3165 | +156
SMTP Client(1,2,3) | +16323 | +26709 | +526
SNMP Agent(1,4) | +14280 | +25041 | +492
SNTP Client(1,3) | +4644 | +5715 | +208
SSL Client | +24144 | +44760 | +1400
SSL Server | +24297 | +45867 | +1032
SSL Server/Client | +27888 | +53724 | +1456
TCP | +7989 | +14550 | +204
UDP | +1311 | +1503 | +142
Total(5) | 57960 | 97617 | 1398
Total + SSL(5) | 77160 | 136050 | 2640
Notes: |  |  |
(1): Code size includes the UDP module (required for operation). |  |  |
(2): Code size includes the TCP module (required for operation). |  |  |
(3): Code size includes the DNS module (required for operation). |  |  |
(4): Code size includes the MPFS2 module (required for operation). |  |  |
(5): Total includes the required files, and the ARP, AutoIP, DHCP Client and Server, DNS, |  |  |
Dynamic DNS, HTTP2, ICMP, MPFS2, NBNS, SMTP, SNMP, SNTP, TCP, and UDP modules. |  |  |
(6): Compiled code size exceeds the capacity of the target processor. |  |  |

C32

Module | Program Memory (bytes) Size Optimization (-0s) | Program Memory (bytes) Speed Optimization (-03) | Global Data Memory (bytes)
Required Stack Code - ENC28J60 network controller | 14192 | 32636 | 108
Required Stack Code - MRF24WB0M Wi-Fi controller | 24216 | 34632 | 195
Announce(1) | +3018 | +3214 | +28
AutoIP | +2644 | +2764 | +64
DHCP Client(1) | +6164 | +6384 | +80
DHCP Server(1) | +4192 | +4376 | +36
DNS Client(1) | +4988 | +5656 | +76
Dynamic DNS Client(1,2,3) | +23658 | +35402 | +397
HTTP2 Server/MPFS2(2) | +29362 | +43236 | +351
ICMP Client | +1360 | +1336 | +36
ICMP Server | +360 | +372 | +0
NBNS(1) | +3924 | +4152 | +40
SMTP Client(1,2,3) | +26002 | +40638 | +353
SNMP Agent(1,4) | +20979 | +32247 | +350
SNTP Client(1,3) | +5886 | +6674 | +108
SSL Client | +37622 | +58650 | +581
SSL Server | +37726 | +60946 | +595
SSL Server/Client | +42690 | +67890 | +613
TCP | +13924 | +24656 | +214
UDP | +2356 | +2476 | +20
Total(5) | 85143 | 131412 | 1181
Total + SSL(5) | 112948 | 173585 | 1566
Notes: |  |  |
(1): Code size includes the UDP module (required for operation). |  |  |
(2): Code size includes the TCP module (required for operation). |  |  |
(3): Code size includes the DNS module (required for operation). |  |  |
(4): Code size includes the MPFS2 module (required for operation). |  |  |
(5): Total includes the required files, and the ARP, AutoIP, DHCP Client and Server, DNS, |  |  |
Dynamic DNS, HTTP2, ICMP, MPFS2, NBNS, SMTP, SNMP, SNTP, TCP, and UDP modules. |  |  |
(6): Compiled code size exceeds the capacity of the target processor. |  |  |

Release Notes > Memory Usage


Peripheral Usage

Contents | Index | Home
Previous | Up | Next
Peripheral Usage

Several microcontroller peripherals can/must be used to implement a TCP/IP stack application.

Type | Specific/Configurable | Polled/Interrupt | Purpose
Timer | Timer 0 for PIC18, Timer 1 otherwise | Interrupt. | Used to implement a tick timer
SPI or PMP | Select via #define in HardwareProfile.h. See Hardware Configuration. | Polled. | The SPI module is used to drive the ENC28J60 or MRF24WB0M. An ENCX24J600 can be driven by the SPI module or a PMP module.
SPI | Select via #define in HardwareProfile.h. See External Storage. | Polled. | Used to interface to an EEPROM or Serial Flash chip, as an option to store web pages for MPFS/MPFS2 or the AppConfig structure.
SPI | Select via #define in HardwareProfile.h. See External Storage. | Polled. | Used to interface to a serial RAM as a optional socket allocation method.
Release Notes > Peripheral Usage


Silicon Solutions

Contents | Index | Home
Previous | Next
Silicon Solutions

One of the first choices to make when designing your application is which hardware layer to use. Microchip supports a number of hardware TCP/IP solutions, each with an integrated MAC and/or PHY. The ENC28J60 and ENCX24J600 are stand-alone Ethernet controller chips, developed by Microchip Technology. The MRF24WB0M is a stand-alone 802.11b wireless transceiver. The PIC18F97J60 is a PIC18 microcontroller with an integrated Ethernet peripheral. The PIC32MX7XX/6XX series of 32-bit microcontrollers are high performance devices with integrated Ethernet MAC peripheral (MII/RMII interface to external PHY).

For information about demonstration boards that use these devices, see the Demo Kits section.

Feature | ENC28J60 | ENCX24J600 | PIC18F97J60 | MRF24WB0M | PIC32MX7XX/6XX
Technology | Wired Ethernet | Wired Ethernet | Wired Ethernet | 802.11 Wireless | Wired Ethernet
MAC | Internal | Internal | Internal | Internal | Internal
PHY | Internal (10-Base-T) | Internal (10/100-Base-T) | Internal (10-Base-T) | Internal | External PHY (MII/RMII Interface)
RAM Buffer (bytes) | 8,192 | 24,576 | 3,808 | 14,170 | Configurable descriptors in Internal RAM (128k of Internal RAM)
Interface | SPI | SPI, 8 or 16 bit multiplexed or demultiplexed parallel interface | None (built-in Ethernet MAC/PHY) | SPI | None (built-in Ethernet MAC)
Pins | 28 | 44, 64 | 64/80/100 | 36 | 64/100/121
Package | SOIC, SPDIP, SSOP, QFN (6x6 mm) | TQFP, QFN | TQFP | Surface Mount WiFi I/O module | TQFP, QFN (9x9 mm), BGA
Cryptographic Engines | No | Yes | No | No | No
Pre-programmed MAC address | No(1) | Yes | No(1) | Yes | Yes

1: For devices without a pre-programmed MAC address, you may consider using an EEPROM with a built-in MAC address, such as the device family described here.

Silicon Solutions


Software

Contents | Index | Home
Previous | Next
Software

This section will discuss the computer software applications included with Microchip's 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.

Topics
Name | Description
TCP/IP Configuration Wizard | Describes the TCP/IP Configuration Wizard.
MPFS2 Utility | Documentation for the MPFS2 utility
Hash Table Filter Entry Calculator | Describes the Ethernet Hash Table Calculator.
Microchip TCP/IP Discoverer | Describes the Microchip TCP/IP Discoverer project.
Software


TCP/IP Configuration Wizard

Contents | Index | Home
Previous | Up | Next
TCP/IP Configuration Wizard

The TCP/IP Configuration Wizard is the easiest, safest way to set up firmware (and some hardware) configuration options. It will read and parse configuration settings from a copy of TCPIPConfig.h and then provide a graphical user interface that will easily allow you to view and modify those settings. In addition, if a feature that you enable will require another resource or feature to operate, the additional features will be enabled automatically. The TCP/IP Configuration Wizard will be installed to the Start menu when the TCP/IP Stack is installed.

When you launch the configuration wizard, you will be prompted to enter the path to a copy of TCPIPConfig.h and given the opportunity to modify advanced configuration settings. The advanced setting option will give more precise control over stack features, but will also require a greater working knowledge of Microchip's TCP/IP Stack.

Software > TCP/IP Configuration Wizard


MPFS2 Utility

Contents | Index | Home
Previous | Up | Next
MPFS2 Utility

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 and the older MPFS Classic 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 (for MPFS2) or FTP server (for MPFS Classic).

Topics
Name | Description
Building MPFS2 Images | Describes how to build an MPFS Image
Uploading Pre-built MPFS2 Images | Procedure to upload images to external storage
Advanced MPFS2 Settings | Working with advanced configuration options
MPFS2 Command Line Options | How to use the MPFS2 Utility from the command line
Software > MPFS2 Utility


Building MPFS2 Images

Contents | Index | Home
Previous | Up | Next
Building MPFS2 Images

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 (see the Demo App MDD Getting Started guide for more information).

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 Settings button on the right can be used to configure the correct host name.

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.

Software > MPFS2 Utility > Building MPFS2 Images


Uploading Pre-built MPFS2 Images

Contents | Index | Home
Previous | Up | Next
Uploading Pre-built MPFS2 Images

There are two ways to upload a pre-built image to external storage. The first is described in the Getting Started 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.

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 host name may need to be changed to the one chosen when the board was first configured. 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.

Software > MPFS2 Utility > Uploading Pre-built MPFS2 Images


Advanced MPFS2 Settings

Contents | Index | Home
Previous | Up | Next
Advanced MPFS2 Settings

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.

Software > MPFS2 Utility > Advanced MPFS2 Settings


MPFS2 Command Line Options

Contents | Index | Home
Previous | Up | Next
MPFS2 Command Line Options

To facilitate batch files and automation, the MPFS2 Utility also supports execution from the command line. The syntax is as follows:

MPFS2.jar [options] <SourceDir> <ProjectDir> <OutputFile>

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 table below:

Switch | Short | Description
/BIN | /b | Output a BIN image (Default)
/C18_C32 | /c | Output a C18 or C32 image
/ASM30 | /s | Output an ASM30 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.

Software > MPFS2 Utility > MPFS2 Command Line Options


Hash Table Filter Entry Calculator

Contents | Index | Home
Previous | Up | Next
Hash Table Filter Entry Calculator

This Hash Table receive filter on the ENC28J60, ENCX24J600, and PIC18F97J60 microcontroller family performs a CRC calculation over the six destination address bytes in a received packet, then uses that value as a pointer into the EHT0-EHT7 registers. If the bit that the pointer points to is set, the packet will be received. The Microchip Hash Table Filter Entry Calculator will determine the bit that must be set in this register bank for a given destination address. If you have a fixed MAC address, known at design time, you can set up your Hash Table receive filter in your code using the value obtained from this tool; otherwise, you must use the SetRXHashTableEntry() function to set it during runtime. To use this tool, specify the address of your device, click calculate, and the CRC value and the corresponding bit will be displayed in the output box.

Software > Hash Table Filter Entry Calculator


Microchip TCP/IP Discoverer

Contents | Index | Home
Previous | Up | Next
Microchip TCP/IP Discoverer

The Microchip TCP/IP Discoverer PC project (fomerly known as the Embedded Ethernet Device Discoverer) will aid in embedded product device discovery (with the Announce 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 protocol enabled are connected to the network, they will respond with a UDP packet containing their host name (NBNS) 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.

Software > Microchip TCP/IP Discoverer


Getting Started

Contents | Index | Home
Previous | Next
Getting Started

This section describes the steps necessary to begin using Microchip's TCP/IP Demo Applications. This section contains specific information for setting up and using the generic TCPIP Demo App. Most of this setup information can be applied to get started with other demo applications as well.

Topics
Name | Description
Hardware Setup | Walks through hardware configuration for supported development platforms
Programming and First Run | Programming the device and clearing EEPROM for first run
Configure your WiFi Access Point | Configure the access point to work with the development kit. For information on configuring the MRF24WBOM for your AP refer to "Configuring WiFi Security"
Connecting to the Network | Connecting your development board to the network
Uploading Web Pages | Uploading web pages to the device
Accessing the Demo Application | Accessing the demo application
Configuring WiFi Security | Configure the wireless access point and demo code for security
Getting Started


Hardware Setup

Contents | Index | Home
Previous | Up | Next
Hardware Setup

The first step to use the stack is to make sure an appropriate development board is configured. To get started, select a platform from the topics presented below.

Topics
Name | Description
Daughter Boards | Describes the daughter boards used to provide TCP/IP functionality to Microchip Demo boards.
PICDEM.net 2 | Development platform for PIC18F97J60 series 8-bit MCU with integrated Ethernet MAC+PHY
PIC18 Explorer | Development platform for 8-bit parts using external ENC28J60, ENC424J600, ENC624J600, or MRF24WB0M MAC+PHY.
Explorer 16 and PIC32 Starter Kit | Development platforms for 16- and 32-bit parts using external ENC28J60, ENC424J600, ENC624J600, or MRF24WB0M MAC+PHY.
PIC24FJ256DA210 Dev Board | Development platform for the PIC24FJ256DA210 using external ENC28J60, ENC424J600, ENC624J600, or MRF24WB0M MAC+PHY.
Getting Started > Hardware Setup


Daughter Boards

Contents | Index | Home
Previous | Up | Next
Daughter Boards

Microchip offers four daughter boards that provide different Ethernet functionality to available demo boards. Each board is designed with:

  • A PICtail™ connector, which enables an interface to the PICDEM.net 2 or the PIC18 Explorer board (populated with a PIC18 processor)

and/or

  • A PICtail Plus connector, which will allow it to interface to an Explorer 16 development board (populated with a PIC24, dsPIC33, or PIC32 processor) or a PIC32 Starter Kit.

Note that the PICDEM.net 2 is populated by default with an ENC28J60 and a PIC18F97J60.

Ethernet PICtail Daughter Board

The Ethernet PICtail Daughter board is populated with an ENC28J60, an RJ-45 connector (with integrated magnetics), and the few other components required for Ethernet operation. It provides a 10-Base-T Ethernet connection for any demo board with a PICtail connector. This daughter board has been largely superseded by the PICDEM.net 2 for debugging Ethernet applications using the PIC18. Visit the Microchip web site to view the Ethernet PICtail [image] Product Page.

Ethernet PICtail Plus Daughter Board

The Ethernet PICtail Plus Daughter Board is the PICtail Plus version of the Ethernet PICtail Daughter Board. It allows the interface of an ENC28J60 to any demo board with a PICtail Plus connector. Visit the Microchip web site to view the Ethernet PICtail Plus Daughter Board [image] Product Page.

Fast 100Mbps Ethernet PICtail Plus Daughter Board

The Fast 100Mbps Ethernet PICtail Plus Daughter Board provides a method for testing and demonstrating the ENC624J600 Ethernet Controller. The board is designed for flexibility and can be connected to a PICtail or a PICtail plus connector. In addition, it is designed to allow the use of any of the parallel or SPI connection modes featured on the ENC624J600 on the PICtail Plus connector. This daughter board provides 10/100-Base-T functionality. Visit the Microchip web site to view the Fast 100Mbps Ethernet PICtailTM Plus Daughter Board [image] Product Page.

Microchip 802.11b WiFi PICtail Plus Daughter Board

The Micorchip 802.11b WiFi PICtail Plus Daughter Board is a demonstration board for evaluating Wi-Fi connectivity on boards with a PICtail or a PICtail Plus connector. The board features the Microchip MRF24WB0MA module, which includes a Wi-Fi transceiver and associated circuit elements. Visit the Microchip Web Site to view more information on [image] Wireless Solutions and the 802.11b WiFi PICtail [image] Product Page..

Getting Started > Hardware Setup > Daughter Boards


PICDEM.net 2

Contents | Index | Home
Previous | Up | Next
PICDEM.net 2

Visit the Microchip web site to view the PICDEM.net 2 [image] Product Page.

The PICDEM.net 2 development board comes populated with a PIC18F97J60 with an integrated Ethernet controller, as well as a standalone ENC28J60 Ethernet controller. The integrated controller is connected to the left Ethernet jack (closest to the LCD), and the standalone part is connected to the right one. By default the stack is configured to use the integrated controller, so the left port should be connected to the network cable. No other configuration of the board is necessary.

The User's Guide that shipped with this development board may refer to an older version of the TCP/IP Stack. This document updates much of that documentation for version 5.36.2.

Using the Fast Ethernet PICtail

By default, this board will use the ENC28J60 or the PIC18F97J60 for Ethernet communication. However, by connecting the Fast Ethernet PICtail to the PICtail connector on the board, you can use it to test the ENC624J600. To use the Fast Ethernet PICtail, insert it as shown in the picture, with header J4 on the PICtail inserted into connector J5 on the demo board.

The Fast Ethernet PICtail is designed to use the SPI communication bus when connected through a PICtail header, so the jumper settings are unused in this configuration, with one exception: the JP2 jumper on the PICtail, labeled ISENSE, should be shorted. The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC624J600 functionality; for manual configuration information, see the ENCX24J600 configuration page.

Using the Microchip 802.11b WiFi PICtail

The PICDEM.net 2 can be used to debug wireless functionality by connecting the PICtail as show in the picture, with header J1 on the PICtail inserted into connector J5 on the demo board.

Note if jumper JP3 exists, it must be shorted between pins 2 and 3 when used on this development platform.

Once your hardware is configured, you can program your board with your preferred demo project. The next few topics in the Getting Started section of this help file provide a tutorial for setting up the generic TCPIP demo application.

Getting Started > Hardware Setup > PICDEM.net 2


PIC18 Explorer

Contents | Index | Home
Previous | Up | Next
PIC18 Explorer

Visit the Microchip web site to view the PIC18 Explorer [image] Product Page.

The PIC18 Explorer is for evaluation of high pin-count PIC18 microcontrollers. By connecting a TCP/IP daughter board to it, you can test and debug Ethernet functionality with a variety of PIC18s. The PIC18F97J60 family includes a built-in Ethernet peripheral, making it the default low-cost, PIC18 Ethernet development platform; the PICDEM.net 2 is the recommended development board for this part.

When using the PIC18 Explorer, ensure that jumpers JP2 and JP3 are shorted to enable the LCD and EEPROM, and switch S4 is configured to properly select the on-board PIC or the ICE setting, as your application requires.

Using the Ethernet PICtail

Unlike the PICDEM.net 2, the PIC18 Explorer does not include an ENC28J60 on the board. To enable testing and debugging using the ENC28J60, you must connect an Ethernet PICtail, as shown in the picture (insert header J2 into connector J3 on the demo board).

When using this configuration, short pins 2 and 3 on jumper J9, to indicate that the PIC18 Explorer is providing a 5V power supply. The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC28J60 functionality; for manual configuration information, see the ENC28J60 configuration page.

Using the Fast Ethernet PICtail

By connecting the Fast Ethernet PICtail to the PICtail connector on the board, you can use it to test the ENC624J600. To use the Fast Ethernet PICtail, insert it as shown in the picture, with header J4 on the PICtail inserted into connector J3 on the demo board.

The Fast Ethernet PICtail is designed to use the SPI communication bus when connected through a PICtail header, so the jumper settings are unused in this configuration, with one exception: the JP2 jumper on the PICtail, labeled ISENSE, should be shorted. The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC624J600 functionality; for manual configuration information, see the ENCX24J600 configuration page.

Using the Microchip 802.11b WiFi PICtail

The PIC18 Explorer can be used to debug wireless functionality by connecting the PICtail as show in the picture, with header J1 on the PICtail inserted into connector J3 on the demo board.

Note if jumper JP3 exists, it must be shorted between pins 2 and 3 when used on this development platform.

Once your hardware is configured, you can program your board with your preferred demo project. The next few topics in the Getting Started section of this help file provide a tutorial for setting up the generic TCPIP demo application.

Getting Started > Hardware Setup > PIC18 Explorer


Explorer 16 and PIC32 Starter Kit

Contents | Index | Home
Previous | Up | Next
Explorer 16 and PIC32 Starter Kit

Visit the Microchip web site to view the Explorer 16 [image] Product Page and the PIC32 Starter Kit [image] Product Page.

The Explorer 16 board is an all-purpose demonstration and development board for 16-bit and 32-bit parts. It can be expanded for TCP/IP support using the Ethernet PICtail Plus, Fast 100Mbps Ethernet PICtail Plus, or 802.11b WiFi PICtail Plus daughter board.

Before using the Explorer 16, check that:

  1. Switch S2 selects PIM
  2. Jumper J7 selects PIC24 (even though the label reads PIC24, this jumper setting selects the programming signals to any PIC on the Explorer 16).

The PIC32 Starter Kit performs a similar function for 32-bit PIC32 parts. By using the [image] PIC32 I/O Expansion Board you can connect the same PICtail Plus board that connect to the Explorer 16.

Using the Ethernet PICtail Plus

To enable testing and debugging of the ENC28J60 on these boards, you must connect an Ethernet PICtail Plus, as shown in the picture (insert header J2 into the upper card-edge connector J5 (Explorer 16) or J4 (I/O Expansion Board)). Note that for some demos, the Ethernet PICtail Plus will need to be inserted into the center card-edge connector of the PICtail Plus connector to use the SPI2 module. See the Demo Compatibility Table for more information.

The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC28J60 functionality; for manual configuration information, see the ENC28J60 configuration page.

Using the Fast Ethernet PICtail Plus

By connecting the Fast 10/100 Ethernet PICtail Plus to the PICtail Plus connector on your board, you can use it to test the ENC624J600. The Fast Ethernet PICtail Plus can be used with these boards in either serial (SPI) or parallel communication mode. For serial mode, connect header J2 of the daughter board to connector J5 (Explorer 16) or J4 (I/O Expansion Board), as seen in the pictures. When operating in serial mode, the jumpers on the Fast Ethernet PICtail are unused, with one exception: the JP2 jumper on the PICtail, labeled ISENSE, should be shorted.

To use the Fast Ethernet PICtail Plus board in parallel mode, insert header J1 into connector J5 of the Explorer 16 or J4 of the I/O Expansion Board, as seen in the pictures. In this configuration, the jumpers must be shorted or opened corresponding to the parallel communication mode being used. A matrix outlining which jumper connections must be made for the jumpers labeled PSPCFG3, PSPCFG2, PSPCFG1&4, PMA to AD, and PMA to A is printed on the back side of the daughter board.

The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC624J600 functionality; for manual configuration information, see the ENCX24J600 configuration page.

Using the Microchip 802.11b WiFi PICtail

The Explorer 16 and PIC32 Starter Kit can be used to debug wireless functionality by connecting the PICtail as show in the pictures, with header J2 on the PICtail inserted into the top slot of connector J5 (Explorer 16) or J4 (I/O Expansion Board) on the demo boards.

Note if jumper JP3 exists, it must be shorted between pins 1 and 2 when used on this development platform.

Once your hardware is configured, you can program your board with your preferred demo project. The next few topics in the Getting Started section of this help file provide a tutorial for setting up the generic TCP/IP demo application.

Getting Started > Hardware Setup > Explorer 16 and PIC32 Starter Kit


PIC24FJ256DA210 Dev Board

Contents | Index | Home
Previous | Up | Next
PIC24FJ256DA210 Dev Board

Visit the Microchip web site to view the PIC24FJ256DA210 Development Kit [image] Product Page.

The PIC24FJ256DA210 Development Kit is a low cost and efficient development kit to evaluate the features and performance of the PIC24FJ256DA210 with integrated graphics, mTouch™ and USB.

You can add network connectivity to this demo board by inserting an Ethernet PICtail Plus, Fast Ethernet PICtail Plus, or Microchip 802.11b WiFi PICtail into the PICtail Plus connector on the demo board. The method for doing this is functionally identical to the method used for the Explorer 16 and PIC32 Starter Kit.

Getting Started > Hardware Setup > PIC24FJ256DA210 Dev Board


Programming and First Run

Contents | Index | Home
Previous | Up | Next
Programming and First Run

Once the hardware is configured, you are ready to program the device for the first time.

Project Setup

Open a session of the MPLAB IDE.

  1. From the "File" menu, select "Import." Browse to the Precompiled Hex subdirectory in your demo project directory and select the *.hex file that matches your hardware setup. The hex file names describe the hardware that the file has been compiled for. For example, the file "Microchip Solutions v2011-06-02\TCPIP\Demo App\Precompiled Hex\C18-PICDN2_ETH97 18F97J60.hex" corresponds to the generic TCP/IP Demo application for the PIC18F97J60 on the PICDEM.net 2, using the PIC's internal Ethernet module. A document enumerating the abbreviations used in the hex file and project file names is available in the Microchip Solutions v20xx-xx-xx/Help directory.
  2. Verify that the MPLAB IDE processor target selection and linker script (if one is present) match the part on your demonstration board (ex: PIC18F97J60).

Note that the projects and source code used to build each hex file are present in the project directory. The hardware and firmware configuration files used to build each project are included in the Configs subdirectory.

Programming

Select your device programmer from the Programmer menu in MPLAB, and then use the Program shortcut button or the Program menu option to program the code you imported to your board.

Clearing the EEPROM

The TCP/IP Stack stores network configuration settings (such as the host name, MAC address, default static IP addresses, SNMP strings, WiFi network name (SSID), etc) in external EEPROM on the board. The demo project will detect if the default values have been changed in the EEPROM, and if so, use the new values. If not, the demo will use the default values configured in TCPIPConfig.h and WF_Config.h. Checksums stored in the EEPROM are used to determine if the structures stored in EEPROM are valid. Manually clearing the EEPROM will allow the demo to resume using the default settings.

Use the following procedure to clear the EEPROM:

  1. Make sure the development board is programmed and not in debug mode
  2. Disconnect the MPLAB® ICD 2/3 or MPLAB REAL ICETM from the board
  3. Press and hold BUTTON0 (RD13/S4 on Explorer 16 or RB3/S5 on PICDEM.netTM 2)
  4. Press and release the MCLR button
  5. Continue holding BUTTON0 until several LEDs flash indicating that EEPROM has been cleared. This takes about 4 seconds.
  6. Release BUTTON0
  7. Press and release MCLR again to reset the software

Once you see LED0 (right-most LED) blinking, the software is running and ready for use.

If you are using the MRF24WB0M WiFi PICtail, you'll need to configure your wireless access point first. For all Ethernet devices, Connect your Development Board to your network.

Getting Started > Programming and First Run


Configure your WiFi Access Point

Contents | Index | Home
Previous | Up | Next
Configure your WiFi Access Point

To run the Wi-Fi demos with the MRF24WB0M PICtail, you'll also need to setup a wireless access point. As an example, this guide will walk through the setup of a Linksys WRT54G2 access point.

Access Point Browser GUI

The Linksys, along with many other popular router brands, uses a built-in webserver on the router to administer the network (both wired and wireless). Please consult the documentation that came with your router for more information on configuration and setup. For a list of known compatible routers refer to section "Access Point Compatibility". To gain access to this web page, you'll need to point your browser to http://192.168.1.1. By default, the username field is left blank, and the password is admin.

Linksys WRT54G2 login page

Wireless Setup

Along the top of the webpage, there should be many tabs for all the different features of the access point. One of the tabs should read "Wireless". After clicking the tab, you will be presented with the Wi-Fi protected setup page. You'll need to click the manual tab to be able to enter your own wireless settings to match the demo.

Linksys default wireless settings

The out of box demo is looking for an AP with the following parameters (note that the SSID is case sensitive):

SSID | MicrochipDemoAP
Security | None
Channel | Either 1, 6, or 11

You should have settings similar to the following:

Linksys wireless manual setup

Once the network is setup, you can connect your device to the network.

Getting Started > Configure your WiFi Access Point


Connecting to the Network

Contents | Index | Home
Previous | Up | Next
Connecting to the Network

All devices on a TCP/IP network must be assigned an IP address. Whereas the MAC address is the hardware address of the device, the IP address is a software address. The DHCP (Dynamic Host Configuration Protocol) allows this assignment to take place automatically (for more address information and configuration options, see the Addresses topic).

The demo application comes with both a DHCP server and DHCP client configured. This allows the board to connect to most networks without configuration. If a free Ethernet port is available on a nearby router, switch, or wall plate, the board can be connected directly using any standard straight-through Ethernet cable. Under this configuration, the board will attempt to obtain an IP address from your network's DHCP server.

If this method is not possible, a crossover Ethernet cable can be used to connect the board directly to a PC's Ethernet port. Using this configuration, the board will act as its own DHCP server and will assign a single IP address to the computer. (The Fast 100Mbps Ethernet PICtail Plus and some newer PCs do not require a special crossover cable, so any Ethernet cable can be used.)

Connect the development board to the network and wait for the link LED on the Ethernet jack to light up. The board is now on the network and capable of communicating with other devices.

If the link LED on the Ethernet jack does not light, your board cannot link to the network. Ensure that you have selected the proper cable, and try switching from a straight-through to a crossover cable, or vice versa.

Now that the board is online, you can Upload the Demo Web Pages.

Getting Started > Connecting to the Network


Uploading Web Pages

Contents | Index | Home
Previous | Up | Next
Uploading Web Pages

Web pages are stored as an MPFS2 image. This image can be placed in either external non-volatile storage (EEPROM or SPI Flash), or in the microcontroller's internal Flash program memory. For this example, the EEPROM chip ( [image] 25LC256) on your demo board will be programmed with a pre-built MPFS2 BIN image. This location can be changed via a compile-time option in TCPIPConfig.h.

The target application on the development board must be running for this procedure to work. Make sure the right most status LED is blinking.

Each hex file is configured to provide a Host Name for your development board. This will be the name by which your board is accessed. In the default hex files, the host name is mchpboard, so you board can be accessed at http://mchpboard. This host name uses the NetBIOS Name Service. It is only available on your local subnet, and will not be accessible from the Internet. Note that this service is not supported by all operating systems. If you have difficulty accessing your board, try using the IP address shown on the LCD screen instead (e.g. access the board at http://192.168.1.101). You can also determine the IP address by using the Microchip TCP/IP Discoverer.

Open a web browser and access the board at http://mchpboard/mpfsupload. This form will allow web pages stored on the device to be updated. If you mistype this URL, the board will provide a default HTTP 404 error page with a link to the MPFS Upload page. This default 404 page will not appear if you've configured your browser to override custom error pages (e.g. by checking "Show friendly HTTP error messages" in Internet Explorer 7's internet options menu). Select the file MPFSImg2.bin from the TCPIP\Demo App folder as shown below.

This update method is only available when using external storage.

When the Upload button is clicked, the MPFS image is sent to the board and programmed into the EEPROM. As this happens, the activity LED on the Ethernet jack will blink. Once the browser reports that the upload has completed, click the link provided within the status message to access the board's web pages.

You can now Access the Demo Application.

Getting Started > Uploading Web Pages


Accessing the Demo Application

Contents | Index | Home
Previous | Up | Next
Accessing the Demo Application

The board is now accessible at the mchpboard host name or at the board's IP address. When accessed in a web browser, a real-time update of the board's controls is displayed. The demo application will show off several features, and will explain how to modify the web pages and application to suit various needs.

If you attempt to access the Network Configuration or SNMP Configuration web pages from the red menu on the left, you will be prompted for a username and password. The default username is "admin" and the default password is "microchip". More information is available on the Authentication web page, or in the HTTP2 server authentication help topic.

Some features of the default demo application may not be available on certain hardware platforms. For more information, see the TCPIP Demo App Features by Hardware Platform topic. For information about how to use each feature of the TCP/IP Demo Application, consult the subtopics in the TCP/IP Demo Application Demo Modules topic.

Once you have finished exploring the demo application, you can proceed to the Stack API section to learn more about the stack and start developing your own application.

If you are exploring the Wi-Fi demo applications and want to set up security, you can get more information on the WLAN security page.

Getting Started > Accessing the Demo Application


Configuring WiFi Security

Contents | Index | Home
Previous | Up | Next
Configuring WiFi Security

The MRF24WB0M can be configured to connect to wireless networks with encryption enabled. The MRF24WB0M supports WEP (40-bit and 104-bit), as well as WPA (TKIP) and WPA2 (TKIP/AES).

Device Security Modes

Security settings for the MRF24WB0M are located in the file WF_Config.h. To enable security features the #define preprocessor definition for MY_DEFAULT_WIFI_SECURITY_MODE must be defined as one of the following options:

WF_SECURITY_WEP_40 | 40-bit WEP security. This equates to 5 ASCII characters or 10 hex digits. MY_DEFAULT_WEP_KEYS_40 contains up to four keys that can be programmed (default is key 0).
WF_SECURITY_WEP_104 | 104-bit WEP security. This equates to 13 ASCII characters or 26 hex digits. MY_DEFAULT_WEP_KEYS_104 contains up to four keys that can be programmed (default is key 0).
WF_SECURITY_WPA_WITH_KEY WF_SECURITY_WPA2_WITH_KEY WF_SECURITY_WPA_AUTO_WITH_KEY | Uses the 32 bytes in MY_DEFAULT_PSK as the key to join the network. These values are generated from a hash of the SSID name and WPA passphrase. For the purpose of the demo, the 32-bytes in MY_DEFAULT_PSK in WF_Config.h correspond to an SSID of "MicrochipDemoAP" and passphrase "Microchip 802.11 Secret PSK Password".
WF_SECURITY_WPA_WITH_PASS_PHRASE WF_SECURITY_WPA2_WITH_PASS_PHRASE WF_SECURITY_WPA_AUTO_WITH_PASS_PHRASE | Instructs the MRF24WB0M to generate the 32 byte PSK using the SSID and passphrase. The default in WF_Config.h corresponds to an SSID of "MicrochipDemoAP" and passphrase "Microchip 802.11 Secret PSK Password". Note that it takes approximately 30 seconds for the MRF24WB0M to calculate this value[1].

Note: Some routers try to increase the random nature of the WEP key by adding an additional layer that will convert an ASCII passphrase into a hexadecimal key. The MRF24WB0M PICtail will require a hexadecimal key, no matter which way it is generated.

Access Point Security Settings

The access point will also need to be changed to match the same security settings. Wireless security settings can be found in the "Wireless Security" tab under the main "Wireless" tab (example shows a Linksys WRT5G2). The drop-down box for security has all the different security options. Note that for WPA/WPA2, the MRF24WB0M only supports personal security levels (as opposed to enterprise, which is not supported).

Linksys security options

[1]: Once the 32-byte PSK is calculated, it can be retrieved by the host from the MRF24WB0M. The host can then save this key to external non-volatile memory. On future connection attempts, the host can program the MRF24WB0M with the WF_SECURITY_*_WITH_KEY options, provide the saved key, and not have to wait 30 seconds to reconnect to the network.

Pre-generated PSK

You also have the option to pre-generate the PSK and use the 32-byte PSK directly in the source code. One handy tool to generate the PSK can be found online at the Wireshark Foundation [image] http://www.wireshark.org/tools/wpa-psk.html. The Wireshark website can generate the expected 32-byte PSK key with the SSID name and the passphrase. You can then use these values in the variable MY_DEFAULT_PSK in TCPIPConfig.h.

Getting Started > Configuring WiFi Security


Demo Information

Contents | Index | Home
Previous | Next
Demo Information

This section describes Microchip's TCP/IP Demo projects, including information about demo-hardware compatibility. For information about how to load and configure the demos, please consult the Getting Started section.

Topics
Name | Description
Demo Compatibility Table | Describes the hardware platforms that are compatible with each Demo.
Available Demos | The TCP/IP Stack comes with several example applications. These applications are described in the following sections.
Demo Information


Demo Compatibility Table

Contents | Index | Home
Previous | Up | Next
Demo Compatibility Table

Each stack demonstration project comes with several predefined, tested configurations. Pre-built hex files for each demo are available in the Precompiled Hex subdirectory in that demo's project folder (i.e. the files for Demo App are located in <install directory>\Microchip Solutions v20xx-xx-xx\TCPIP\Demo App\Precompiled Hex). This section will specify the combinations of demo boards, processors, MAC/PHY layers, and communication buses that are set up to work by default.

TCPIP Demo App

Demo Board | Processor | MAC/PHY Layer | Comm. Bus | Notes
PIC18 Explorer | 18F87J11 | ENC28J60 | SPI | Requires silicon revision A4 or later.
PIC18 Explorer | 18F87J11 | ENCX24J600 | SPI |
PIC18 Explorer | 18F87J11 | MRF24WB0M | SPI |
PIC18 Explorer | 18F87J50 | ENC28J60 | SPI |
PIC18 Explorer | 18F87J50 | ENCX24J600 | SPI |
PIC18 Explorer | 18F87J50 | MRF24WB0M | SPI |
PIC18 Explorer | 18F8722 | ENC28J60 | SPI |
PIC18 Explorer | 18F8722 | ENCX24J600 | SPI |
PIC18 Explorer | 18F8722 | MRF24WB0M | SPI |
PICDEM.net 2 | 18F97J60 | ETH97J60 | - |
PICDEM.net 2 | 18F97J60 | ENC28J60 | SPI |
PICDEM.net 2 | 18F97J60 | ENCX24J600 | SPI |
PICDEM.net 2 | 18F97J60 | MRF24WB0M | SPI |
Explorer 16 | 24FJ128GA010 | ENC28J60 | SPI |
Explorer 16 | 24FJ128GA010 | ENCX24J600 | SPI |
Explorer 16 | 24FJ128GA010 | MRF24WB0M | SPI |
Explorer 16 | 24FJ128GA010 | ENCX24J600 | PSP 5 Indirect |
Explorer 16 | 24FJ256GA110 | ENC28J60 | SPI2 |
Explorer 16 | 24FJ256GA110 | ENCX24J600 | SPI2 |
Explorer 16 | 24FJ256GA110 | ENCX24J600 | PSP 5 Indirect |
Explorer 16 | 24FJ256GA110 | MRF24WB0M | SPI2 |
Explorer 16 | 24FJ256GB110 | ENC28J60 | SPI |
Explorer 16 | 24FJ256GB110 | ENCX24J600 | SPI |
Explorer 16 | 24FJ256GB110 | ENCX24J600 | PSP 5 Indirect |
Explorer 16 | 24FJ256GB110 | MRF24WB0M | SPI |
Explorer 16 | 24FJ256GB210 | ENC28J60 | SPI |
Explorer 16 | 24FJ256GB210 | ENCX24J600 | SPI |
Explorer 16 | 24FJ256GB210 | ENCX24J600 | PSP 5 Indirect Bitbang |
Explorer 16 | 24FJ256GB210 | MRF24WB0M | SPI |
Explorer 16 | 33FJ256GP710 | ENC28J60 | SPI |
Explorer 16 | 33FJ256GP710 | ENCX24J600 | SPI |
Explorer 16 | 33FJ256GP710 | ENCX24J600 | PSP 5 Indirect |
Explorer 16 | 33FJ256GP710 | MRF24WB0M | SPI |
Explorer 16 | 32MX360F512L | ENC28J60 | SPI |
Explorer 16 | 33EP512MU810 | ENC28J60 | SPI2 |
Explorer 16 | 24EP512GU810 | ENC28J60 | SPI2 |
Explorer 16 | 32MX360F512L | ENCX24J600 | SPI |
Explorer 16 | 32MX360F512L | ENCX24J600 | PSP 5 Indirect |
Explorer 16 | 32MX360F512L | ENCX24J600 | PSP 9 |
Explorer 16 | 32MX360F512L | MRF24WB0M | SPI |
Explorer 16 | 32MX460F512L | ENC28J60 | SPI |
Explorer 16 | 32MX460F512L | ENCX24J600 | SPI |
Explorer 16 | 32MX460F512L | MRF24WB0M | SPI |
Explorer 16 | 32MX795F512L | ENC28J60 | SPI |
Explorer 16 | 32MX795F512L | ENCX24J600 | SPI |
Explorer 16 | 32MX795F512L | MRF24WB0M | SPI |
PIC24FJ256DA210 Development Board | 24FJ256DA210 | ENC28J60 | SPI |
PIC24FJ256DA210 Development Board | 24FJ256DA210 | ENCX24J600 | SPI |
PIC24FJ256DA210 Development Board | 24FJ256DA210 | ENCX24J600 | PSP 5 Indirect Bitbang |
PIC24FJ256DA210 Development Board | 24FJ256DA210 | MRF24WB0M | SPI |
PIC32 General Purpose Starter Kit (DM320001) | 32MX360F512L | ENC28J60 | SPI |
PIC32 General Purpose Starter Kit (DM320001) | 32MX360F512L | ENCX24J600 | SPI |
PIC32 General Purpose Starter Kit (DM320001) | 32MX360F512L | ENCX24J600 | PSP 5 Indirect |
PIC32 General Purpose Starter Kit (DM320001) | 32MX360F512L | MRF24WB0M | SPI |
PIC32 USB Starter Kit (DM320003_2) | 32MX795F512L | ENC28J60 | SPI2 |
PIC32 USB (DM320003_2) | 32MX795F512L | ENCX24J600 | SPI2 |
PIC32 USB (DM320003_2) | 32MX795F512L | ENCX24J600 | PSP 5 Indirect |
PIC32 USB (DM320003_2) | 32MX795F512L | ENCX24J600 | PSP 9 |
PIC32 USB (DM320003_2) | 32MX795F512L | MRF24WB0M | SPI2 |
PIC32 Ethernet Starter Kit | 32MX795F512L | Internal MAC, National DP83848C PHY | - |
dsPIC33E USB Starter Kit | 33EP512MU810 | ENCX24J600 | SPI2 |
dsPIC33E USB Starter Kit | 33EP512MU810 | ENCX24J600 | PSP 5 |
dsPIC33E USB Starter Kit | 33EP512MU810 | ENCX24J600 | PSP 5 Indirect |
dsPIC33E USB Starter Kit | 33EP512MU810 | MRF24WB0M | SPI2 |
PIC24E USB Starter Kit | 24EP512GU810 | ENCX24J600 | SPI2 |
PIC24E USB Starter Kit | 24EP512GU810 | ENCX24J600 | PSP5 |
PIC24E USB Starter Kit | 24EP512GU810 | ENCX24J600 | PSP 5 Indirect |
PIC24E USB Starter Kit | 24EP512GU810 | MRF24WB0M | SPI2 |

TCPIP WebVend

Demo Board | Processor | MAC/PHY Layer | Comm. Bus | Notes
PICDEM.net 2 | 18F97J60 | ENC28J60 | SPI |
PICDEM.net 2 | 18F97J60 | ETH97J60 | - |
Explorer 16 | 24FJ128GA010 | ENC28J60 | SPI |
Explorer 16 | 24FJ128GA010 | ENCX24J600 | SPI |
Explorer 16 | 24FJ128GA010 | MRF24WB0M | SPI |
Explorer 16 | 33FJ256GP710 | ENC28J60 | SPI |
Explorer 16 | 33FJ256GP710 | ENCX24J600 | SPI |
Explorer 16 | 33FJ256GP710 | MRF24WB0M | SPI |
Explorer 16 | 32MX360F512L | ENC28J60 | SPI |
Explorer 16 | 32MX360F512L | ENCX24J600 | SPI |
Explorer 16 | 32MX360F512L | MRF24WB0M | SPI |
Explorer 16 | 32MX460F512L | ENC28J60 | SPI |
Explorer 16 | 32MX460F512L | ENCX24J600 | SPI |
Explorer 16 | 32MX460F512L | MRF24WB0M | SPI |
Explorer 16 | 32MX795F512L | ENC28J60 | SPI |
Explorer 16 | 32MX795F512L | ENCX24J600 | SPI |
Explorer 16 | 32MX795F512L | MRF24WB0M | SPI |

TCPIP WiFi EasyConfig Demo App

Demo Board | Processor | MAC/PHY Layer | Comm. Bus | Notes
Explorer 16 | 24FJ128GA010 | MRF24WB0M | SPI |
Explorer 16 | 33FJ256GP710 | MRF24WB0M | SPI |
Explorer 16 | 32MX360F512L | MRF24WB0M | SPI |
Explorer 16 | 32MX460F512L | MRF24WB0M | SPI |
Explorer 16 | 32MX795F512L | MRF24WB0M | SPI |
PIC24FJ256DA210 Development Board | PIC24FJ256DA210 | MRF24WB0M | SPI |

TCPIP WiFi Console Demo App

Demo Board | Processor | MAC/PHY Layer | Comm. Bus | Notes
PICDEM.net 2 | 18F97J60 | MRF24WB0M | SPI |
Explorer 16 | 24FJ128GA010 | MRF24WB0M | SPI |
Explorer 16 | 33FJ256GP710 | MRF24WB0M | SPI |
Explorer 16 | 32MX360F512L | MRF24WB0M | SPI |
Explorer 16 | 32MX460F512L | MRF24WB0M | SPI |
Explorer 16 | 32MX795F512L | MRF24WB0M | SPI |
PIC24FJ256DA210 Development Board | PIC24FJ256DA210 | MRF24WB0M | SPI |

TCPIP Internet Radio App

Demo Board | Processor | MAC/PHY Layer | Comm. Bus | Notes
Internet Radio Board | 18F67J60 | ENC28J60 | SPI |

TCPIP Internet Bootloader

Demo Board | Processor | MAC/PHY Layer | Comm. Bus | Notes
N/A | 18F66J60 | ETH97J60 | - |
N/A | 18F66J60 | ETH97J60 | - | Extended Instruction Mode
N/A | 18F66J65 | ETH97J60 | - |
N/A | 18F66J65 | ETH97J60 | - | Extended Instruction Mode
N/A | 18F67J60 | ETH97J60 | - |
N/A | 18F67J60 | ETH97J60 | - | Extended Instruction Mode
N/A | 18F86J60 | ETH97J60 | - |
N/A | 18F86J60 | ETH97J60 | - | Extended Instruction Mode
N/A | 18F86J65 | ETH97J60 | - |
N/A | 18F86J65 | ETH97J60 | - | Extended Instruction Mode
N/A | 18F87J60 | ETH97J60 | - |
N/A | 18F87J60 | ETH97J60 | - | Extended Instruction Mode
N/A | 18F96J60 | ETH97J60 | - |
N/A | 18F96J60 | ETH97J60 | - | Extended Instruction Mode
N/A | 18F96J65 | ETH97J60 | - |
N/A | 18F96J65 | ETH97J60 | - | Extended Instruction Mode
N/A | 18F97J60 | ETH97J60 | - |
N/A | 18F97J60 | ETH97J60 | - | Extended Instruction Mode

TCPIP MDD Demo App

Demo Board | Processor | MAC/PHY Layer | Comm. Bus | Notes
Explorer 16 | PIC24FJ256GB110 | ENC28J60 | SPI | Uses USB Thumb Drive as a storage medium for web pages.
Explorer 16 | PIC24FJ128GA010 | ENC28J60 | SPI | Uses SD Card as a storage medium for web pages.

Google Map

For information on the Google Map demo compatibility, see the file "Getting Started - Running the Graphics Google Map Demo" in the Combo Demos/Google Map directory in your Microchip Applications Library installation directory.

Demo Information > Demo Compatibility Table


Available Demos

Contents | Index | Home
Previous | Up | Next
Available Demos

The TCP/IP Stack comes with several example applications. These applications are described in the following sections.

Topics
Name | Description
Demo App | Main demo application for the TCP/IP Stack.
Internet Bootloader | Implements a TFTP bootloader for the PIC18F97J60 family of parts.
WebVend | Sample Web-Enabled Vending Machine application used by the TCP/IP Webinar series.
Internet Radio | Implements a stand-alone Internet radio receiver.
WiFi Console | Implements a wireless console demo application that accepts client commands.
WiFi EZConfig | Implements a wireless application to configure an embedded device for a network in which the device has no natural human interface mechanism (i.e. keyboard and display). This demo also demonstrates dynamic scanning of networks and getting back calculated PSK keys from the MRF24W device.
Demo App MDD | Variation of TCPIP Demo App that uses an SD card or USB Thumb Drive to store web pages.
Google PowerMeter | Implements a power monitoring application that uploads data to Google PowerMeter.
Energy Monitoring | Implements a power monitoring application that uploads data to Google PowerMeter using the PIC18F87J72 Energy Monitoring PICtail Plus Daughter Board.
Demo Information > Available Demos


Demo App

Contents | Index | Home
Previous | Up | Next
Demo App

The TCPIP\Demo App project folder contains the main demo application for the Microchip TCP/IP Stack. Besides showing example applications using the web server, e-mail client, SNMP server, and more, this application also includes examples for implementing custom application layers. Details about these applications are provided here.

For a list of pre-tested demo hardware configurations, please consult the Demo Compatibility Table. Unspecified hardware configurations may also be useable with the Demo App, but some additional configuration may be necessary.

Some demo features are disabled in certain Demo App projects to support the associated hardware platform and TCP/IP controller. Please consult the following table to determine which features are available on which configurations:

Topics
Name | Description
TCPIP Demo App Features by Hardware Platform | Describes which features of the TCP/IP Demo Application are available for each hardware configuration.
Demo Modules | Describes the custom modules used in this demo.
Demo Information > Available Demos > Demo App


TCPIP Demo App Features by Hardware Platform

Contents | Index | Home
Previous | Up | Next
TCPIP Demo App Features by Hardware Platform

Some hardware platforms cannot support all of the features implemented in the TCP/IP Demo Application. The following table outlines which features are available for each combination of demo board and MAC/PHY layer supported natively by the TCP/IP Demo App. Note that this table will not appear in the PDF version of the help file; see the "TCPIP Demo App Features.htm" file in the TCPIP documentation folder in the Microchip Application Library help folder.

Platforms |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PICDEM.net 2 - ENC28J60 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PICDEM.net 2 - ETH97J60 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PICDEM.net 2 - ENC624J600 (SPI) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PICDEM.net 2 - MRF24JWB0M |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC18 Explorer - ENC28J60 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC18 Explorer - ENC624J500 (SPI) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC18 Explorer - MRF24JWB0M |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Explorer 16 - ENC28J60 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Explorer 16 - ENC624J600 (SPI) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Explorer 16 - ENC624J600 (PSP 5 - Indirect) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Explorer 16 - ENC624J600 (PSP 9) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Explorer 16 - MRF24JWB0M |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC24FJ256DA210 Dev Board - ENC28J60 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC24FJ256DA210 Dev Board - ENC624J600 (SPI) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC24FJ256DA210 Dev Board - ENC624J600 (PSP 5 - Indirect) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC24FJ256DA210 Dev Board - MRF24JWB0M |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC32 GP/USB Starter Kits - ENC28J60 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC32 GP/USB Starter Kits - ENC624J600 (SPI) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC32 GP/USB Starter Kits - ENC624J600 (PSP 5 - Indirect) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC32 GP/USB Starter Kits - ENC624J600 (PSP 9) |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC32 GP/USB Starter Kits - MRF24JWB0M |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
PIC32 Ethernet Starter Kit - ETH795 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Features |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
MPFS EEPROM Storage |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
MPFS SPI Flash Storage |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
MPFS Internal Storage |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
UART Output |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
UART-to-TCP Bridge |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
ICMP Client |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
DHCP Server |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
SMTP Client |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
SNMP Server |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Telnet Server |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Generic TCP Client Demo |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Generic TCP Server Demo |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
SNTP Client |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Berkeley Socket API |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
UDP TX Checksum Calculation |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
HTTP Email Demo |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
NVM Storage |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
LCD Display |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Potentiometer |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
Buttons | 3 | 3 | 2 | 3 | 3 | 3 | 0 | 0 | 0 | 0 | 4 | 4 | 4 | 4 | 4 | 2 | 2 | 2 | 2 | 4 | 4 | 4
LEDs | 3 | 3 | 3 | 3 | 3 | 3 | 3 | 3 | 3 | 3 | 7 | 6 | 6 | 7 | 7 | 8 | 8 | 8 | 8 | 8 | 8 | 8

NVM Storage

A board with Non-Volatile Memory can modify and save its configuration variables at runtime. In the TCP/IP Demo App, this allows you to change the board name, IP Address, wireless SSID, wireless security, or other configuration parameters via a web page interface. The data will be written to SPI Flash or EEPROM and then used to reinitialize the board if it is reset. A board without this feature will always use the default settings after power-up.

Buttons and LEDs

The TCP/IP Stack-compatible demo boards have a variable number of buttons and LEDs. By default, the TCP/IP Demo App is configured to display and accept input from 8 LEDs and 4 buttons on the demo's index page; the buttons and LEDs used depend on what is available on the board.

Demo Information > Available Demos > Demo App > TCPIP Demo App Features by Hardware Platform


Demo Modules

Contents | Index | Home
Previous | Up | Next
Demo Modules

Several custom modules are used in this demo. This section will describe the components and functionality of these modules.

Modules
Name | Description
Web Page Demos | Provides an example for building a custom HTTP application using the HTTP2 server and allows several other demo features to be accessed and controlled via web interface.
E-mail (SMTP) Demo | Demonstrates how to use an e-mail client to send messages when events occur. This is a standalone demo; for the web page "Send Email" demo, see the Forms using POST topic.
Generic TCP Client | Demonstrates how to build a TCP Client application through an HTTP client example.
Generic TCP Server | Demonstrates how to build a TCP server application
Ping (ICMP) Demo | Demonstrates how to build a Ping client.
Network Management (SNMP) Server | Describes the Simple Network Management Protocol Demo.
Topics
Name | Description
UART-to-TCP Bridge | Describes how to use the UART-to-TCP Bridge demo.
Zero Configuration (ZeroConf) | Describes usage of the Zeroconf modules
Demo Information > Available Demos > Demo App > Demo Modules


Web Page Demos

Contents | Index | Home
Previous | Up | Next
Web Page Demos
Functions | Variables

The CustomHTTPApp.c file demonstrates how to build a custom HTTP application on top of the HTTP2 server. All the features of the TCPIP Demo App web pages are implemented here. Examples can be found for handling Authentication, processing web forms (using HTTP GET and POST), and providing status information through the output of dynamic variables.

Topics
Name | Description
Dynamic Variables | Dynamic variables allow the PIC to output custom data when serving a web page.
Authentication | Authentication requires a correct username/password prompt before displaying select web pages.
Forms using GET | Web forms are easier to process when using the GET method, but the amount of data is limited.
Forms using POST | Forms using POST are more difficult to process, but large amounts of data can be submitted.
Cookies | Cookies allow storage of session information in a user's browser.
Functions | The following table lists functions in this documentation.
Variables | The following table lists variables in this documentation.
Functions
Name | Description
HTTPPostSNMPCommunity | This is function HTTPPostSNMPCommunity.
HTTPPostConfig | Processes the configuration form on config/index.htm
HTTPPostDDNSConfig | Parsing and collecting http data received from http form.
HTTPPostEmail | Processes the e-mail form on email/index.htm
HTTPPostLCD | Processes the LCD form on forms.htm
HTTPPostMD5 | Processes the file upload form on upload.htm
Variables
Name | Description
DDNSData | RAM allocated for DDNS parameters
lastFailure | Stick status message variable. See lastSuccess for details.
lastSuccess | Sticky status message variable. This is used to indicated whether or not the previous POST operation was successful. The application uses these to store status messages when a POST operation redirects. This lets the application provide status messages after a redirect, when connection instance data has already been lost.
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos


Dynamic Variables

Contents | Index | Home
Previous | Up | Next
Dynamic Variables

Overview

This section describes how to view dynamic variables in the TCP/IP Demo App HTTP2 demo. For information about how to implement dynamic variables in your own page, see the HTTP2 dynamic variables topic.

Instructions

  1. Program your board with the demo code and upload the demo app web page. Open your web browser and navigate to the board's web page (http://mchpboard by default).
  2. Observe the LED output, button state, and potentiometer reading in the box in the upper right of the web page. The button and potentiometer values will be updated dynamically based on the status of the buttons on your board. In addition, if you click the LEDs to toggle them, their status will be dynamically updated on the page. Note that some LEDs or buttons may not be implemented, depending on your hardware setup. Consult the TCPIP Demo App Features by Hardware Platform topic for more information.

  3. Observe the current Stack Version and Build Date in the top center of the Overview Page.
  4. Navigate to the Dynamic Variables page using the navigation panel on the left of the page.
  5. Observe the Build Date and Time, LED state, stack version, and current IP address- these variables are output to this page dynamically when it's downloaded by the browser.

Exercises

You can optionally complete the exercises described on the Dynamic Variables page. You may want to read the HTTP2 dynamic variables topic first. The first exercise is to implement the display of LED0 on the dynamic variable demo page.

  1. Start by opening dynvars.htm in your "TCPIP Demo App\WebPages2" folder.
  2. Locate the dynamic variables in the page and replace the question mark with a dynamic variable to display the value of LED 0. You can use the other LED variables as a template, but specify 0 as the LED to open.

  3. In your MPLAB project, open CustomHTTPApp.c and ensure that the HTTPPrint_led function (if you used ~led(0)~ as your dynamic variable) if written to output data when 0 is passed in as a parameter.
  4. Rebuild your web page with the MPFS2 Utility.
  5. Rebuilt your project, and reprogram your board. Navigate to the dynamic variable page and verify that the LED0 field reflects the status of the LED on your board. Since the LED on your board is blinking, you may need to refresh the web page to view its current status.

The second exercise on this page simply demonstrates how to dynamically insert a file into a web page.

  1. Start by opening dynvars.htm in your "TCPIP Demo App\WebPages2" folder.
  2. Locate the dynamic variables that include header.inc and footer.inc. Observe the difference between the declaration of these variables and the other variables on the page.
Module

Web Page Demos

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Dynamic Variables


Authentication

Contents | Index | Home
Previous | Up | Next
Authentication

Overview

This section describes how to use the authentication demo in the TCP/IP Demo App HTTP2 demo. For information about how to implement authentication in your own page, see the HTTP2 Authentication topic.

Instructions

  1. Program your board with the demo code and upload the demo app web page. Open your web browser and navigate to the board's web page (http://mchpboard by default).
  2. Navigate to the Authentication page using the navigation panel on the left of the page.
  3. Note the authentication user name ("admin") and password ("microchip").
  4. Click on the "Access Restricted Page" link on the Authentication page.

  5. Enter an incorrect combination of usernames and passwords. The browser will not advance to the Access Restricted Page. After 3 incorrect username/password combinations, the browser will be redirected to an "Unauthorized" screen.
  6. Click the back button in your browser. Click on the "Access Restricted Page" link and enter the correct username and password.
  7. You will advance to the "Login Successful" page. Your browser will store this username/password combination until it is closed and reopened.

Exercise

You can optionally complete the exercise described on the "Login Successful" page. In this exercise, you will change the username and password that you use to log in to this page.

  1. Open CustomHTTPApp.c in your TCP/IP Demo App MPLAB project.
  2. Locate the HTTPCheckAuth function.
  3. Change the values being compared to the function inputs to a username and password of you choosing.
  4. Rebuild your project and program your board.
Module

Web Page Demos

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Authentication


Forms using GET

Contents | Index | Home
Previous | Up | Next
Forms using GET

Overview

This section describes how to use web forms in the TCP/IP Demo App HTTP2 demo. For information about how to implement forms in your own page, see the HTTP2 form processing topic.

Instructions

  1. Program your board with the demo code and upload the demo app web page. Open your web browser and navigate to the board's web page (http://mchpboard by default).
  2. Observe the LED state on the board. Click on an LED indicator in the box on the top right of the Overview page. Verify that the LED state changes on the board. Note that some LEDs or buttons may not be implemented, depending on your hardware setup. Consult the TCPIP Demo App Features by Hardware Platform topic for more information.
  3. Navigate to the Form Processing page using the navigation panel on the left of the page.
  4. Select new LED states in the pull-down boxes. Click "Save" and observe that the LED states of your board changed to match the settings you selected.

Exercise

You can optionally complete the exercise described on the "Form Processing" page. In this exercise, you will change the example to support LED5. You may want to read the HTTP2 form processing topic first.

  1. Start by opening forms.htm in your "TCPIP Demo App\WebPages2" folder.
  2. Locate the GET method implementation the will display the LEDs. You should see select forms for the four LEDs that are already implemented. Each of these has two options: the On option will send a '1' to the server when submitted and the Off option will send a '0' when submitted. Each of the declarations of these options also use the ledSelected dynamic variable to determine which option will be selected by default, based on the current status of the corresponding LED on the board. This dynamic variable accepts two arguments: the first defines which LED is being checked, and the second describes the state being checked for. So, for example, the ~ledSelected(4,TRUE)~ variable will be replaced by the word "SELECTED" if LED4 is on when this variable callback function is called. In this case, ~ledSelected(4,FALSE)~ would be replaced by nothing. This would result in the 'On' option being selected by default in the page.
  3. Create a new select input for LED5.
  4. Open CustomHTTPApp.c in the TCP/IP Demo App MPLAB project.
  5. Verify that the HTTPPrint_ledSelected dynamic variable callback function has been implemented for LED5.
  6. Find the HTTPExecuteGet function. Locate the section of code the processes GET arguments for the forms.htm file.
  7. Add implementation to search for the "led5" argument string in the GET data buffer and then set LED5_IO based on the associated value.
Module

Web Page Demos

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Forms using GET


Forms using POST

Contents | Index | Home
Previous | Up | Next
Forms using POST

Overview

This section describes how to use web forms in the TCP/IP Demo App HTTP2 demo. For information about how to implement forms in your own page, see the HTTP2 form processing topic.

Instructions

  1. Program your board with the demo code and upload the demo app web page. Open your web browser and navigate to the board's web page (http://mchpboard by default).
  2. Navigate to the Form Processing page using the navigation panel on the left of the page.
  3. Enter a text string into the "LCD" text box and click on "Save." Verify that this string was written to the LCD display on your demo board.

  4. Navigate to the File Uploads page using the navigation panel on the left of the page.
  5. Browser for a file on your computer and click "Get MD5." The application will read your file using a series of POST transfers and calculate and display and MD5 hash of the contents.

  6. Navigate to the Send E-mail page using the navigation panel on the left of the page.
  7. Fill in the form fields with the appropriate information.
    1. No SSL - You will need a local SMTP server that does not require a secure connection. Enter the address in the SMTP Server field, set the port to 25, and enter your user name and password for the server. Set the "To:" field to the email recipient and press "Send Message."
    2. SSL - Enter the address of a public SMTP server (e.g. smtp.gmail.com). Set the port number to 465 or 587. Enter your email account information (e.g. username@gmail.com and your Gmail password). Set the "To:" field to the email recipient and press "Send Message." Note that some corporate subnets may block outgoing secure traffic on the SMTP port. If this is the case, you'll have to establish a VPN tunnel outside this network or connect your board to a network that's not blocked by this type of firewall. You must have installed the Microchip Data Encryption Libraries to use SSL, and SSL Client support must be enabled. See the SSL API topic for more information.

  8. Verify that the e-mail was received on the recipient e-mail address.
Module

Web Page Demos

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Forms using POST


Cookies

Contents | Index | Home
Previous | Up | Next
Cookies

Overview

This section describes how to use the cookie demo in the TCP/IP Demo App HTTP2 demo. For information about how to implement cookies in your own page, see the HTTP2 Cookies topic.

Instructions

  1. Program your board with the demo code and upload the demo app web page. Open your web browser and navigate to the board's web page (http://mchpboard by default).
  2. Navigate to the Cookies page using the navigation panel on the left of the page.
  3. Type your first name into the "First Name" text box and click "Set Cookies." Verify that the name was read successfully and displayed in the "Name" output field.

Exercise

You can optionally complete the exercise described on the "Cookies" page. In this exercise, you will create a cookie called "fav" with the value in the favorite field in the example box. You may want to read the HTTP2 dynamic variable, GET, and cookie topics first.

  1. Start by opening cookies.htm in your "TCPIP Demo App\WebPages2" folder.
  2. Locate the code for the example box that displays the name and favorite PIC architecture. Replace the "not implemented" string with a dynamic variable to output the data from the cookie.
  3. Locate the code for the select box form input for the favorite architecture. Note the value of the name field of the select form.
  4. Open CustomHTTPApp.c in the TCP/IP Demo App MPLAB project. Locate the HTTPExecuteGet function and find the code that handles GET method inputs from cookies.htm.
  5. Set the value of curHTTP.hasArgs to indicate that two form arguments are present in the data buffer.
  6. In CustomHTTPApp.c, create a function to output data for the dynamic variable you created in step 2. The name of the function will depend on the name of the variable. For a variable named ~cookiefavorite~ you would implement a function called HTTPPrint_cookiefavorite. This function should search through the curHTTP.data data buffer to try and find a name/value pair with the name equal to the name of your select form from step 3. If it finds it, it should write the value for that pair to the TCP buffer; otherwise, it should write "not set." See the implementation of HTTPPrint_cookiename for an example.
Copy Code
void HTTPPrint_cookiename(void)
{
    BYTE *ptr;

    ptr = HTTPGetROMArg(curHTTP.data, (ROM BYTE*)"name");

    if(ptr)
        TCPPutString(sktHTTP, ptr);
    else
        TCPPutROMString(sktHTTP, (ROM BYTE*)"not set");

    return;
}
  7. Compile your web page using the MPFS2 Utility and upload it to your board. You may receive a warning that your dynamic variables have changed in your page.
  8. Rebuild your project and program your board.
  9. Verify that both cookies can be set.
Module

Web Page Demos

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Cookies


Functions

Contents | Index | Home
Previous | Up | Next
Functions
Functions
Name | Description
HTTPPostSNMPCommunity | This is function HTTPPostSNMPCommunity.
HTTPPostConfig | Processes the configuration form on config/index.htm
HTTPPostDDNSConfig | Parsing and collecting http data received from http form.
HTTPPostEmail | Processes the e-mail form on email/index.htm
HTTPPostLCD | Processes the LCD form on forms.htm
HTTPPostMD5 | Processes the file upload form on upload.htm
Module

Web Page Demos

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Functions


HTTPPostSNMPCommunity Function

Contents | Index | Home
Previous | Up | Next
HTTPPostSNMPCommunity Function
C
static HTTP_IO_RESULT HTTPPostSNMPCommunity();
Description

This is function HTTPPostSNMPCommunity.

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Functions > HTTPPostSNMPCommunity Function


HTTPPostConfig Function

Contents | Index | Home
Previous | Up | Next
HTTPPostConfig Function
C
static HTTP_IO_RESULT HTTPPostConfig();
Description

Accepts configuration parameters from the form, saves them to a temporary location in RAM, then eventually saves the data to EEPROM or external Flash.

When complete, this function redirects to config/reboot.htm, which will display information on reconnecting to the board.

This function creates a shadow copy of the AppConfig structure in RAM and then overwrites incoming data there as it arrives. For each name/value pair, the name is first read to curHTTP.data[0:5]. Next, the value is read to newAppConfig. Once all data has been read, the new AppConfig is saved back to EEPROM and the browser is redirected to reboot.htm. That file includes an AJAX call to reboot.cgi, which performs the actual reboot of the machine.

If an IP address cannot be parsed, too much data is POSTed, or any other parsing error occurs, the browser reloads config.htm and displays an error message at the top.

Preconditions

None

Return Values
Return Values | Description
HTTP_IO_DONE | all parameters have been processed
HTTP_IO_NEED_DATA | data needed by this function has not yet arrived
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Functions > HTTPPostConfig Function


HTTPPostDDNSConfig Function

Contents | Index | Home
Previous | Up | Next
HTTPPostDDNSConfig Function
C
static HTTP_IO_RESULT HTTPPostDDNSConfig();
Description

This routine will be excuted every time the Dynamic DNS Client configuration form is submitted. The http data is received as a string of the variables seperated by '&' characters in the TCP RX buffer. This data is parsed to read the required configuration values, and those values are populated to the global array (DDNSData) reserved for this purpose. As the data is read, DDNSPointers is also populated so that the dynamic DNS client can execute with the new parameters.

Preconditions

curHTTP is loaded.

Return Values
Return Values | Description
HTTP_IO_DONE | 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
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Functions > HTTPPostDDNSConfig Function


HTTPPostEmail Function

Contents | Index | Home
Previous | Up | Next
HTTPPostEmail Function
C
static HTTP_IO_RESULT HTTPPostEmail();
Description

This function sends an e-mail message using the SMTP client and optionally encrypts the connection to the SMTP server using SSL. It demonstrates the use of the SMTP client, waiting for asynchronous processes in an HTTP callback, and how to send e-mail attachments using the stack.

Messages with attachments are sent using multipart/mixed MIME encoding, which has three sections. The first has no headers, and is only to be displayed by old clients that cannot interpret the MIME format. (The overwhelming majority of these clients have been obseleted, but the so-called "ignored" section is still used.) The second has a few headers to indicate that it is the main body of the message in plain- text encoding. The third section has headers indicating an attached file, along with its name and type. All sections are separated by a boundary string, which cannot appear anywhere else in the message.

Preconditions

None

Return Values
Return Values | Description
HTTP_IO_DONE | the message has been sent
HTTP_IO_WAITING | the function is waiting for the SMTP process to complete
HTTP_IO_NEED_DATA | data needed by this function has not yet arrived
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Functions > HTTPPostEmail Function


HTTPPostLCD Function

Contents | Index | Home
Previous | Up | Next
HTTPPostLCD Function
C
static HTTP_IO_RESULT HTTPPostLCD();
Description

Locates the 'lcd' parameter and uses it to update the text displayed on the board's LCD display.

This function has four states. The first reads a name from the data string returned as part of the POST request. If a name cannot be found, it returns, asking for more data. Otherwise, if the name is expected, it reads the associated value and writes it to the LCD. If the name is not expected, the value is discarded and the next name parameter is read.

In the case where the expected string is never found, this function will eventually return HTTP_IO_NEED_DATA when no data is left. In that case, the HTTP2 server will automatically trap the error and issue an Internal Server Error to the browser.

Preconditions

None

Return Values
Return Values | Description
HTTP_IO_DONE | the parameter has been found and saved
HTTP_IO_WAITING | the function is pausing to continue later
HTTP_IO_NEED_DATA | data needed by this function has not yet arrived
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Functions > HTTPPostLCD Function


HTTPPostMD5 Function

Contents | Index | Home
Previous | Up | Next
HTTPPostMD5 Function
C
static HTTP_IO_RESULT HTTPPostMD5();
Description

This function demonstrates the processing of file uploads. First, the function locates the file data, skipping over any headers that arrive. Second, it reads the file 64 bytes at a time and hashes that data. Once all data has been received, the function calculates the MD5 sum and stores it in curHTTP.data.

After the headers, the first line from the form will be the MIME separator. Following that is more headers about the file, which we discard. After another CRLFCRLF, the file data begins, and we read it 16 bytes at a time and add that to the MD5 calculation. The reading terminates when the separator string is encountered again on its own line. Notice that the actual file data is trashed in this process, allowing us to accept files of arbitrary size, not limited by RAM. Also notice that the data buffer is used as an arbitrary storage array for the result. The ~uploadedmd5~ callback reads this data later to send back to the client.

Preconditions

None

Return Values
Return Values | Description
HTTP_IO_DONE | all parameters have been processed
HTTP_IO_WAITING | the function is pausing to continue later
HTTP_IO_NEED_DATA | data needed by this function has not yet arrived
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Functions > HTTPPostMD5 Function


Variables

Contents | Index | Home
Previous | Up | Next
Variables
Module

Web Page Demos

Variables
Name | Description
DDNSData | RAM allocated for DDNS parameters
lastFailure | Stick status message variable. See lastSuccess for details.
lastSuccess | Sticky status message variable. This is used to indicated whether or not the previous POST operation was successful. The application uses these to store status messages when a POST operation redirects. This lets the application provide status messages after a redirect, when connection instance data has already been lost.
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Variables


DDNSData Variable

Contents | Index | Home
Previous | Up | Next
DDNSData Variable
C
BYTE DDNSData[100];
Description

RAM allocated for DDNS parameters

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Variables > DDNSData Variable


lastFailure Variable

Contents | Index | Home
Previous | Up | Next
lastFailure Variable
C
BOOL lastFailure = FALSE;
Description

Stick status message variable. See lastSuccess for details.

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Variables > lastFailure Variable


lastSuccess Variable

Contents | Index | Home
Previous | Up | Next
lastSuccess Variable
C
BOOL lastSuccess = FALSE;
Description

Sticky status message variable. This is used to indicated whether or not the previous POST operation was successful. The application uses these to store status messages when a POST operation redirects. This lets the application provide status messages after a redirect, when connection instance data has already been lost.

Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos > Variables > lastSuccess Variable


E-mail (SMTP) Demo

Contents | Index | Home
Previous | Up | Next
E-mail (SMTP) Demo

Overview

This file provides two examples for using the SMTP client module to send e-mail messages. The first transmits short alert messages whose entire bodies can be stored in RAM at once. The second example demonstrates how to generate messages on-the-fly when the entire body cannot be allocated in RAM. (This second example is commented. You must comment the first example and uncomment this one to use it.)

A third example of using the SMTP client is provided in HTTPPostEmail. This example shows how to send messages with attachments, as well as how to dynamically configure the recipient and e-mail server at run-time.

Instructions (Short Message Demo)

  1. Open your project in MPLAB and open SMTPDemo.c. Scroll down to the MAIL_BEGIN case in the switch statement in the SMTPDemo() function.
    1. Replace the initializer of the RAMStringTo[] array with the target email address.
    2. Replace the initializer of the SMTPClient.Server.szROM structure element with the address of your mail server. Note that this demo does not include security features, so you will need a mail server that does not require SSL. To test this functionality with a mail server that does support SSL (including most public mail servers), please use the HTTPPostEmail SMTP demo.
  2. Compile the code, program your board, and run the demo.
  3. Press buttons 2 and 3 on your board to transmit an email message. LED1 on your board will indicate that the message is being transmitted; LED2 will indicate that is was sent successfully. Check the BUTTON2_IO, BUTTON3_IO, LED1_IO, and LED2_IO macros in the copy of HardwareProfile.h that corresponds to your project to determine which buttons and LEDs are used for your hardware setup.
  4. Verify that the message was received by the email account you specified in the RAMStringTo[] array.

Description

The short-message SMTPDemo task function implements a four-state state machine. When the board is powered on, the state machine is initialized to the SM_HOME state, in which it waits for buttons 2 and 3 to be pressed. Once they are pressed, the task will enter the MAIL_BEGIN state.

In the MAIL_BEGIN state, the task will attempt to requisition the SMTP module. Once it's able to do this, it will populate the SMTPClient structure with message parameters and transmit the message. It will then enter the MAIL_SMTP_FINISHING state.

In the MAIL_SMTP_FINISHING state, the task will check a callback function (SMTPIsBusy) to determine when the module is finished. It will then give up control of the SMTP module and toggle LEDs based on the successful operation of the SMTP module. The state machine will then enter the MAIL_DONE state, which will wait at least 1 second before transitioning back to MAIL_HOME, allowing another email to be sent.

Functions
Name | Description
SMTPDemo | Demonstrates use of the e-mail (SMTP) client.
Demo Information > Available Demos > Demo App > Demo Modules > E-mail (SMTP) Demo


SMTPDemo Function

Contents | Index | Home
Previous | Up | Next
SMTPDemo Function
C
void SMTPDemo();
Description

This function demonstrates the use of the SMTP client. The function is called periodically by the stack, and checks if BUTTON2 and BUTTON3 are pressed simultaneously. If they are, it attempts to send an e-mail message using parameters hard coded in the function below.

While the client is executing, LED1 will be used as a busy indicator. LED2 will light when the transmission has been completed successfully. If both LEDs extinguish, an error occurred.

For an example of sending a longer message (one that does not exist in RAM all at once), see the commented secondary implementation of this function in this file (SMTPDemo.c) below. For an example of sending a message using parameters gathered at run time, and/or a message with attachments, see the implementation of HTTPPostEmail in CustomHTTPApp.c.

Preconditions

The SMTP client is initialized.

Returns

None

Module

E-mail (SMTP) Demo

Demo Information > Available Demos > Demo App > Demo Modules > E-mail (SMTP) Demo > SMTPDemo Function


Generic TCP Client

Contents | Index | Home
Previous | Up | Next
Generic TCP Client
Variables

Overview

The Generic TCP Client provides an example of how to build an HTTP client (or any other TCP client) using the Microchip TCP/IP Stack. It will print out the results from a search engine query to the PIC's UART module. The result data can be viewed on a PC terminal.

Instructions

  1. Connect the programmed demo board to a router that is connected to the Internet.
  2. Connect your PC to your demo board with an RS-232 cable. Open a terminal program like HyperTerminal, and configure it to the following settings: 19200 bps, 8 data bits, No parity, 1 stop bit, No flow control.
  3. Press Button 1 on your demo board (check the BUTTON1_IO macro in the copy of HardwareProfile.h that corresponds to your project to determine which button is Button 1).
  4. Observe the search results for "Microchip" at www.microchip.com on your terminal.

Description

The Generic TCP Client demo implements a task function with five states. When the board is powered on, the initial state will be set to SM_DONE. This state will wait for the user to press Button 1; when a button-press event occurs, the state will switch to SM_HOME. In the SM_HOME state, the task will attempt to open a TCP client socket. This socket will use a TCP_PURPOSE_GENERIC_TCP_CLIENT socket type from the TCP socket structure that was initialized in your configuration files. The targeted server will be the Google search engine, and the server port will be 80, the port used for HTTP connections. The task will switch the state machine to the SM_SOCKET_OBTAINED state.

The task will wait in the SM_SOCKET_OBTAINED state until a connection is established with Google or a 5-second timeout elapses. If a timeout occurs, the state will close the socket and change the state back to SM_HOME. Otherwise, it will wait until the TCP buffer can accept 125 bytes of data and then use an HTTP GET to search for the word "Microchip" at the site "microchip.com." Once the GET has been sent, the state will switch to SM_PROCESS_RESPONSE.

In the SM_PROCESS_RESPONSE state, the task will wait until a response is received or the socket was disconnected. If a response is received, it will print it to the UART. In either case, the task will transition to the SM_DISCONNECT state, where it will close the client socket and return to the SM_DONE state.

Functions
Name | Description
GenericTCPClient | Implements a simple HTTP client (over TCP).
Topics
Name | Description
Variables | The following table lists variables in this documentation.
Variables
Name | Description
RemoteURL | Defines the URL to be requested by this HTTP client
ServerName | Defines the server to be accessed for this application
ServerPort | Defines the port to be accessed for this application
Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Client


GenericTCPClient Function

Contents | Index | Home
Previous | Up | Next
GenericTCPClient Function
C
void GenericTCPClient();
Description

This function implements a simple HTTP client, which operates over TCP. The function is called periodically by the stack, and waits for BUTTON1 to be pressed. When the button is pressed, the application opens a TCP connection to an Internet search engine, performs a search for the word "Microchip" on "microchip.com", and prints the resulting HTML page to the UART.

This example can be used as a model for many TCP and HTTP client applications.

Preconditions

TCP is initialized.

Returns

None

Module

Generic TCP Client

Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Client > GenericTCPClient Function


Variables

Contents | Index | Home
Previous | Up | Next
Variables
Module

Generic TCP Client

Variables
Name | Description
RemoteURL | Defines the URL to be requested by this HTTP client
ServerName | Defines the server to be accessed for this application
ServerPort | Defines the port to be accessed for this application
Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Client > Variables


RemoteURL Variable

Contents | Index | Home
Previous | Up | Next
RemoteURL Variable
C
ROM BYTE RemoteURL[] = "/search?as_q=Microchip&as_sitesearch=microchip.com";
Description

Defines the URL to be requested by this HTTP client

Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Client > Variables > RemoteURL Variable


ServerName Variable

Contents | Index | Home
Previous | Up | Next
ServerName Variable
C
BYTE ServerName[] = "www.google.com";
Description

Defines the server to be accessed for this application

Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Client > Variables > ServerName Variable


ServerPort Variable

Contents | Index | Home
Previous | Up | Next
ServerPort Variable
C
WORD ServerPort = 80;
Description

Defines the port to be accessed for this application

Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Client > Variables > ServerPort Variable


Generic TCP Server

Contents | Index | Home
Previous | Up | Next
Generic TCP Server
Macros

Overview

The Generic TCP Server example demonstrates how to build a TCP server application. Once you connect to the demo server, it will echo your keystrokes back to you after converting the characters to UPPER CASE.

Instructions

  1. Connect the programmed demo board to a computer either directly or through a router. For Ethernet, a direct connection may require a crossover cable; for WiFi, the board may need to be in AdHoc mode to establish a direct connection.
  2. Determine the IP address of the demo board. This can be done several different ways.
    1. If you are using a demo setup with an LCD display (e.g. Explorer 16 or PICDEM.net 2), the IP address should be displayed on the second line of the display.
    2. Open the Microchip TCP/IP Discoverer from the start menu. Press the "Discover Devices" button to see the addresses and host names of all devices with the Announce Protocol enabled on your network. You may have to configure your computer's firewall to prevent it from blocking UDP port 30303 for this solution.
    3. If your board is connected directly with your computer with a crossover cable:
      1. Open a command/DOS prompt and type 'ipconfig'. Find the network adaptor that is connected to the board. The IP address of the board is located in the 'Default Gateway' field
      2. Open up the network status for the network adaptor that connects the two devices. This can be done by right clicking on the network connection icon in the network settings folder and select 'status' from the menu. Find the 'Default Gateway' field.
  3. Open a command/DOS prompt. Type "telnet ip_address 9760" where ip_address is the IP address that you got from step 2 and 9760 is the TCP port chosen for the Generic TCP Server implementation.
  4. As you type characters, they will be echoed back in your command prompt window in UPPER CASE.
  5. Press Escape to end the demo.

Description

The GenericTCPServer demo implements a task function with 3 states. In the first state, SM_HOME, the task will attempt to open a TCP server socket. This socket will use a TCP_PURPOSE_GENERIC_TCP_SERVER socket type from the TCP socket structure that was initialized in your configuration files. It will also listen on TCP port 9760 (defined by the macro SERVER_PORT).

Once the socket has been successfully opened, the task function will enter the SM_LISTENING state. In this state, the task will always return unless a client has connected to it (by establishing a telnet connection on port 9760). Once a client has connected to the server, the server will read received data from the TCP socket's RX buffer, convert it to upper case, and write it to the TCP socket's TX buffer.

If an Escape character is received, the server will enter the SM_CLOSING state. In this state, it will close the server socket to break the current connection. The server will then re-enter the SM_HOME state, where it will reopen the TCP_PURPOSE_GENERIC_TCP_SERVER socket to listen for new connections.

Functions
Name | Description
GenericTCPServer | Implements a simple ToUpper TCP Server.
Topics
Name | Description
Macros | The following table lists macros in this documentation.
Macros
Name | Description
SERVER_PORT | Defines which port the server will listen on
Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Server


GenericTCPServer Function

Contents | Index | Home
Previous | Up | Next
GenericTCPServer Function
C
void GenericTCPServer();
Description

This function implements a simple TCP server. The function is invoked periodically by the stack to listen for incoming connections. When a connection is made, the server reads all incoming data, transforms it to uppercase, and echos it back.

This example can be used as a model for many TCP server applications.

Preconditions

TCP is initialized.

Returns

None

Module

Generic TCP Server

Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Server > GenericTCPServer Function


Macros

Contents | Index | Home
Previous | Up | Next
Macros
Macros
Name | Description
SERVER_PORT | Defines which port the server will listen on
Module

Generic TCP Server

Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Server > Macros


SERVER_PORT Macro

Contents | Index | Home
Previous | Up | Next
SERVER_PORT Macro
C
#define SERVER_PORT 9760
Description

Defines which port the server will listen on

Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Server > Macros > SERVER_PORT Macro


Ping (ICMP) Demo

Contents | Index | Home
Previous | Up | Next
Ping (ICMP) Demo
Macros

Overview

The Ping Demo explains how to use the ICMP client to check if a remote node is reachable. If the project with this demo includes the DNS module, the PIC will ping "ww1.microchip.com." Otherwise, it will ping the local gateway. This demo is only available on hardware setups with LCD displays (e.g. Explorer 16 or PICDEM.net 2).

Instructions

  1. Press Button 0 on your demo board. Button 0 is usually the rightmost or topmost button on the board (check the BUTTON0_IO macro in the copy of HardwareProfile.h that corresponds to your project to determine exactly which button is Button 0).
  2. When the device receives an echo response from the remote node or when the ping times out, the LCD will be updated with the appropriate information.

Description

The PingDemo task function implements a two-state state machine. The task will wait in the SM_HOME state until the user presses button 0. Once the button is pressed, the task will attempt to obtain ownership of the ICMP module with the ICMPBeginUsage function. If it does, it will send a ping to the specified address and transition to the SM_GET_ICMP_RESPONSE state.

In the SM_GET_ICMP_RESPONSE state, the task will call the ICMPGetReply callback function and take action depending on the return value:

Value | Action
-2 | Remain in this state and keep waiting for a response.
-1 | Write a message to the LCD indicating that the ping timed out. Change state to SM_HOME.
-3 | Write a message to the LCD indicating that the DNS module couldn't resolve the target address. Change state to SM_HOME.
Other | Convert the response time to a text string and print it to the LCD. Change state to SM_HOME.
Functions
Name | Description
PingDemo | Demonstrates use of the ICMP (Ping) client.
Topics
Name | Description
Macros | The following table lists macros in this documentation.
Macros
Name | Description
HOST_TO_PING | Address that ICMP client will ping. If the DNS client module is not available in the stack, then this hostname is ignored and the local gateway IP address will be pinged instead.
Demo Information > Available Demos > Demo App > Demo Modules > Ping (ICMP) Demo


PingDemo Function

Contents | Index | Home
Previous | Up | Next
PingDemo Function
C
void PingDemo();
Description

This function implements a simple ICMP client. The function is called periodically by the stack, and it checks if BUTTON0 has been pressed. If the button is pressed, the function sends an ICMP Echo Request (Ping) to a Microchip web server. The round trip time is displayed on the UART when the response is received.

This function can be used as a model for applications requiring Ping capabilities to check if a host is reachable.

Preconditions

TCP is initialized.

Returns

None

Module

Ping (ICMP) Demo

Demo Information > Available Demos > Demo App > Demo Modules > Ping (ICMP) Demo > PingDemo Function


Macros

Contents | Index | Home
Previous | Up | Next
Macros
Macros
Name | Description
HOST_TO_PING | Address that ICMP client will ping. If the DNS client module is not available in the stack, then this hostname is ignored and the local gateway IP address will be pinged instead.
Module

Ping (ICMP) Demo

Demo Information > Available Demos > Demo App > Demo Modules > Ping (ICMP) Demo > Macros


HOST_TO_PING Macro

Contents | Index | Home
Previous | Up | Next
HOST_TO_PING Macro
C
#define HOST_TO_PING "ww1.microchip.com"    // Address that ICMP client will ping.  If the DNS client module is not available in the stack, then this hostname is ignored and the local gateway IP address will be pinged instead.
Description

Address that ICMP client will ping. If the DNS client module is not available in the stack, then this hostname is ignored and the local gateway IP address will be pinged instead.

Demo Information > Available Demos > Demo App > Demo Modules > Ping (ICMP) Demo > Macros > HOST_TO_PING Macro


Network Management (SNMP) Server

Contents | Index | Home
Previous | Up | Next
Network Management (SNMP) Server
Functions | Macros | Variables

The Microchip SNMP server is a multilingual implementation which supports SNMPv1, V2c and V3 server features simultaneously. SNMP server is implemented to address the requirements of embedded applications. The SNMPv3 support is added with TCPIP Stack Version 5.31. SNMPv1 and V2c are enabled with single macro. The SNMPv3 server could be selectively enabled with an independent macro.

This series of topics will address the application- and demo-specific implementation of an SNMP server included with the TCP/IP Demo applications. For information describing the SNMP module in general, please see the SNMP API topic.

V2c is implemented with support for the configuration of multiple community names, which are stored in selected non-volatile memory (SPI EEPROM or SPI Flash). The community names can be configured through the TCP/IP Configuration Wizard or through the HTTP/MPFS2 web interface. An access-restricted web page is provided with the demo application to allow dynamic configuration of SNMP communities.

SNMPv3 RFC specifies different types of access mechanism, user security model (USM), authentication and privacy protocols. Microchip SNMPv3 server is implemented with support for USM, AES 128 CFB 128 privacy protocol, MD5 and SHA1 message authentication protocols. The demo implementation of the server is configured with 3 different types of user names with respective authentication and privacy credentials and authentication types. These credentials and other user information are stored in the global array. The user of the SNMPv3 stack can decide on the number of user names in the User’s data base to be stored with the Server. According to the SNMPv3 recommendation, SNMPv3 server should not be configured with the authentication and privacy passwords. Instead could be configured with the respective localized keys of the password. Microchip SNMPv3 agent is provided with the password information in the database for the “Getting Started” and for understanding purpose only. It is recommended that the SNMPv3 stack should be modified to restrict access to the password OIDs declared in the user data base.

You will require two firmware packages to run the SNMPv3 server demo. Each of these must be installed in the order listed, as some files will be overwritten. The software encryption library is not required if the SNMPv3 services are not intended.

  1. The Microchip Application Libraries, including TCP/IP Stack v5.31 or later. This code is available at www.microchip.com/mal.
  2. Microchip's Data Encryption Libraries. This demo uses the SSL security layer to communicate with Google. To use SSL with the TCP/IP stack, you will require these libraries. They are available in a CD-based or downloadable format from MicrochipDirect for a small fee (required to comply with U.S. cryptographic export restriction screening). You must execute the "Microchip TCPIP Stack vX.XX Encryption Add-on.exe" installer to install the files required by the demo. The ARCFOUR.c/h and RSA.c/h cryptographic files in this installer will replace the dummy versions found with the default TCP/IP Stack installation.

To enable SNMPv3 functionality, you must add the PIC32_AES.a library from the Data Encryption Libraries to your demo project.

Note: For existing Microchip SNMP V1 and V2c users.

• SNMP V1/V2c users wanting to upgrade the Microchip TCP/IP Stack from older versions to the latest version and continue to use SNMP V1/V2c can get the SNMP V1/V2c services from this agent, provided they do not modify the default settings of the SNMP module in v5.25 onward.

• The implementation framework for V1 and V2c remains the same, except for a few new features and functions. The names and parameters of some of the functions have been changed. V1/V2c users may have to make changes to their application-specific code. There should not be any change in the SNMP stack code unless users have incorporated application code in the SNMP stack.

• Users should build a new MPFS image using the MPFS File System Generator utility and upload it to the selected EEPROM or Flash memory, as the AppConfig structure is updated to accommodate community names in V2c and SNMP engine ID for SNMPv3.

Topics
Name | Description
MIB Files | Describes Management Information Base (MIB) files.
MIB Browsers | Describes SNMP MIB browsers.
SNMP Operations | Describes the SNMP operations supported in this demo.
SNMP Traps | Describes SNMP traps.
HTTP Configuration | Describes how to configure SNMP community names via HTTP.
Functions | The following table lists functions in this documentation.
Variables | The following table lists variables in this documentation.
Macros | The following table lists macros in this documentation.
Functions
Name | Description
SendNotification | Prepare, validate remote node which will receive trap and send trap pdu.
SNMPGetTimeStamp | Obtains the current Tick value for the SNMP time stamp.
Macros
Name | Description
MAX_TRY_TO_SEND_TRAP |
SNMP_MAX_NON_REC_ID_OID | Update the Non record id OID value which is part of CustomSnmpDemo.c file
STACK_USE_SMIV2 | Default STACK_USE_SMIV2 is enabled . For Stack V5.31, STACK_USE_SMIV2 should be disabled.
Variables
Name | Description
gSendTrapSMstate | This is variable gSendTrapSMstate.
gSnmpNonMibRecInfo | OLD snmp.mib file with SMIv1 standard
gSnmpv3UserSecurityName | This is variable gSnmpv3UserSecurityName.
Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server


MIB Files

Contents | Index | Home
Previous | Up | Next
MIB Files

SNMP describes the hierarchal storage of management objects (referred to with object IDs or OIDs) with Management Information Base (MIB) files. The Microchip SNMP server demo includes two MIB files:

• mchip.mib - This is an Abstract Syntax Notation One (ASN.1) formatted MIB file containing information about the variables used in the demo.

• snmp.mib - This is a custom-formatted file that can be parsed to create webpage and header resources that can be accessed with a PIC microcontroller.

The TCP/IP stack includes the mib2bib utility, which will compile the custom Microchip MIB script (snmp.mib) to generate two files called snmp.bib and mib.h. The snmp.bib file is a compressed record of management objects that will be stored with web pages and the mib.h file contains C defines for each OID. These files are included in the appropriate directories for the TCP/IP Demo Apps, but for a custom application you must copy snmp.bib to your web page directory, copy mib.h to your application directory and include it in your project, rebuild your project, and then rebuild and re-upload your web page. This will bundle the BIB file into your web page image, which will allow the SNMP agent to search for the required variable information with the MPFS file system.

Module

Network Management (SNMP) Server

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > MIB files


MIB Browsers

Contents | Index | Home
Previous | Up | Next
MIB Browsers

Several SNMP MIB browsers are available. Users can also install a customized MIB browser specific to their application. This help file describes using the iReasoning MIB browser to run the demo app. The iReasoning MIB browser can be obtained from: http://www.ireasoning.com/downloadmibbrowserlicense.shtml. The MIB script upload, the MIB tree structure display, and the SNMP query mechanism procedures vary from browser to browser.

Note that the use of a MIB browser or other third-party tools may require that users review and agree to the terms of a license. Microchip's reference to the iReasoning MIB browser is for the users' convenience. It is the user's responsibility to obtain information about, and comply with the terms of, any applicable licenses.

Once your browser installation has been completed, perform the following steps:

  1. Copy the mchip.mib file to the MIB file directory of your browser (e.g. "C:\Program Files\ireasoning\mibbrowser\mibs").
  2. Open the iReasoning browser, select File->Load MIBs, and select the mchip.mib, RFC1213.mib and SNMP-FRAMEWORK-MIB.mib (If SNMPv3 server is enabled) file.

The Microchip MIB directory will be displayed in the SNMP MIB pane.

The minimum set of RFC 1213 MIB2 variables that are required to identify the Microchip node as an SNMP node to the network are implemented. These variables can be accessed by any SNMP browser with a "public" type community name. Refer to AN870 - "SNMP V2c Agent for Microchip TCP/IP Stack" for more details on the MIB scripts, community names, and demo SNMP MIB variable tree structure. The following figure shows the variables implemented in the Microchip SNMP Agent.

The ASN.1 format mchip.mib file is defined with a private variable tree structure for the MIB variables. Also the mchp.mib is added with number of OIDs which could be accessed only with SNMPv3 request. The browser can access every variable in the MIB database provided the community name matches. The access to the MIB variables is restricted to the type of the request. The RFC1213 mib variables could be accessed with SNMPv2c/v3 request. But the SNMP-FRAMEWORK-MIB.mib variables could only be accessed with SNMPv3 reqeust if the credentials are matched and the message is authenticated. To modify these MIB variables, corresponding changes must be made to both MIB scripts (snmp.mib and mchip.mib). The following figure shows the Microchip private MIB variable tree structure in the browser.

Configuring the Browser

To configure the iReasoning MIB browser:

  1. Select the "Advanced" tab in the browser.

The following configuration window will be displayed:

  2. If V2C services are required, select SNMP version V2c, configure the Read and Write community to the browser.
    • The V2c agent will respond only to the queries from SNMP MIB browsers using the same community. That is, the V2c agent and the browser should be members of the same community.
    • If the community fields are left blank, the manager sends the SNMP request with the community name as "public."
    • The V2c agent is configured by default with 3 Read communities ("public", "read", "") and 3 Write communities ("private","write","public").
    • The default maximum community length is 8 characters.
    • As the default communities also contain the "public" community name, the agent will respond to all of the browsers requesting the "public" community.
    • The TCP/IP Configuration Wizard can be used to configure the default SNMP community names. At run time, the community names can be dynamically configured using the HTTP interface for SNMP community name configuration.

If the V2c agent receives an SNMP request with an unknown community name, the agent will generate an Authentication trap.

The V2c agent's multiple community support feature enables the user application to provide limited access to the requesting browser based on the community name used by the browser to access the MIB database variables of the agent.

  3. If SNMPv3 services are required, select the SNMP Version as 'V3' in the 'Advanced' tab of the SNMP MIB Browser. The following configuration window will be displayed:

  4. If SNMPv3 services are required, SNMPv3 browser is required to be configured with the user name, authentication and privacy password, message authentication hash type, privacy protocol type. The SNMP server would respond only if one of the user credentials and user security parameters in the below table is configured at the manager. The below table is stored in the global structure with the SNMPv3 server stack. The SNMPv3 server would only respond if the request credentials of the MIB browser matches to that of the stored user data base of the SNMP server.
 | USER 1 | USER 2 | USER 3
USM User | microchip | SnmpAdmin | root
Security Level | auth, priv | auth, no priv | no auth, no priv
Auth Algorithm | MD5 | SHA1 |
Auth password | auth12345 | ChandlerUS |
Privacy Algorithm | AES |  |
Privacy password | priv12345 |  |

  5. The Microchip SNMPv3 stack does support only one Context Engine ID with the server. Leave the "Context Name" option in the "Advanced" tab empty. It is ignored on the server.
  6. According to the user and the auth and privacy protocols configured with the SNMP browser, the UDP authenticated and encrypted message would be exchanged between server and the client.
  • If the USER 1 values, as in above table, are configured in the MIB browser, the data exchange between client and server is encrypted and authenticated. The PDU could be captured in the Ethernet packet sniffer like WireShark and examined. As the data is encrypted and authenticated, the data integrity and the privacy is achieved.
  • If USER 2 values, as in above table, are configured in the MIB browser, the data exchange between client and server is authenticated. The data integrity would be checked once the data is received at either end. The message authentication mechanism protects from the possible data sniffing and modification threat, and alos guarantees that the data is received from the authenticated and guaranteed source.
  • if USER3 values, as in above table, are configured in the MIB browser, the data exchange between client and server is neither authenticated nor encrypted.
  • Considering the above three USER configurations, if the SNMP server is to be accessed over WAN, in the internet cloud, tha data should be encrypted and authenticated to have the highest level of data privacy and integrity.
  7. Configure the IP address of the SNMP agent to the "Address field.

  7. Select the variable to be accessed from the agent MIB database from the SNMP MIBs pane. The selected variable's OID can be seen in the OID tab in the following figure.

  8. Select the SNMP Get operation from the operations tab.

  9. The SNMPv3 server demo MIB is included with RFC1213 SNMPv2 MIB variables, private mib variables and the SNMP-FRAMEWORK-MIB variables. If the SNMPv2C request with validated community name is generated from the MIB Browser, only set of few variables is accessed. The access to the MIB variables is restricted to the type of SNMP version request received. If the SNMPv3 request with correct credentials is generated from the MIB Browser, the complete MIB access is provided.
  10. The user would require to decide on which part of the MIB should be required to be restricted depending upon the SNMP version type. The MIB design is the one of the important step in deciding the MIB tree structure and the variable to be placed accordingly.
  11. The SNMP server demo MIB is added with a static variable OID named as "snmpv3PvtObject" with OID value as 43.6.1.4.1.17095.6.1. This variable is placed in the private branch of the MIB by creating an independent branch. All the other variables in the private branch are accessible by SNMPv2c request. The access to this static variable is restricted by the SNMP version type. Only the SNMPv3 request with correct credentials could access this variable.

Exploring the Demo

After the MIB script is uploaded to the SNMP browser, the MIB tree structure will be displayed in the browser. Any of the variables in this tree can be accessed (using SNMP operations) from the agent if the agent supports these variables. The browser and agent should be members of the same community. To learn more about SNMP operations, PDU types, and terminology, refer to AN870 - "SNMP V2C Agent for Microchip TCP/IP Stack."

Module

Network Management (SNMP) Server

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > MIB Browsers


SNMP Operations

Contents | Index | Home
Previous | Up | Next
SNMP Operations

Get

  1. Select the "Advanced" tab and configure the SNMP version to '1' and the Read community to "public".
  2. Select "Get" from the operations menu.
  3. Select the sysDescr variable from the MIB Tree.

The Result Table displays the sysDescr variable information. Repeat this procedure for any MIB variable. For SNMP V2c, repeat the same procedure, substituting '2' in place of '1' in the version configuration.

As explained earlier, the V2c agent is configured with three Read and Write community defaults. Configure the browser to use any of these communities and try accessing the MIB variables. You should be able to access some of the MIB variables even with the Read Community configured as any of the 'write' community defaults. For GET operations, if the Read or Write community matches, the agent processes the request. For SET operations, the received community names must match any of the 'write' community names.

For SNMP V3, substitute '3' in place of '1' in the version configuration in the "Advanced" tab. Configure the other user based auth and priv credentials as explained in the "MIB Browsers" section.

With appropriate credentials, all the MIB variables are accessible. Select any of the MIB variables in the MIB tree and do a GET operation.

Get_Next

  1. Repeat the process for GET. Select the sysDescr variable from the MIB tree. Select "Get Next" from the operations menu. The result table will display the sysObjectID variable information.
  2. Repeat for additional MIB variables to get the information for the corresponding next variable.

  3. Set the SNMP MIB Browser version to v1/v2c. Try to access the private MIB variable "snmpv3PvtObject" with OID value as 43.6.1.4.1.17095.6.1. The access should be restricted. Set the verison to V3, configre the credentails, again try a Get_Next operation for the sae variable. The access should be granted.

Get_Bulk

This operation is supported in SNMP V2c and SNMP V3. Get_Bulk enables the collection of bulk information from the agent with a single request from the manager.

  1. Configure the SNMP version to '2' or '3' in the SNMP browser.
  2. If version is configured to '2', set the Read Community to 'public' or 'read.'
  3. If version is configured to '3', configure the appropriate V3 credentials.
  4. Select the sysDescr variable from the MIB tree.
  5. Select the Get Bulk operation from the Operations menu.

The result table will display information for 10 MIB variables in a single request (if the Max-Repetitions=10 and Non-Repeaters=0 is configured). These variables are the lexicographical successors of the sysDescr variable. The number of variables that the agent will respond with can be configured in the browser through the menus: "Tools->Options->Non-Repeaters" and "Tools->Options->Max-Repetitions." The Non-Repeaters and Max-Repetitions numbers are extracted by the SNMP agent from the received Get_Bulk request and the number of variables that will be included in the response PDU is calculated. for more information on calculating the number of variables, Non-Repeaters, and Max-Repetitions, refer to RFC 3416.

Set

The Set command updates the variable information of the MIB database in the agent. The Set command can be performed only on those variables which are declared as 'READWRITE' in the MIB scripts, and only if the community name matches any one of the 'write' community names configured with the agent.

  1. Select the ledD5 variable from the MIB tree.
  2. Configure the SNMP version to '1' or '2.' Configure the Write Community to 'public', 'write', or 'private'.
  3. If version is configured to '3', configure the appropriate V3 credentials.
  4. Select 'Set' from the Operations menu.

The SNMP SET window will pop up. Enter the value for the browser in the OID field.

A success message will appear.

A 'Get' operation for the same variable should now return the new 'Set' value for this variable. LED5 on the demo board should now be ON. Repeat the procedure to set LED5 to OFF. LED6 can also be set ON or OFF.

Module

Network Management (SNMP) Server

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > SNMP Operations


SNMP Traps

Contents | Index | Home
Previous | Up | Next
SNMP Traps

The SNMP agent in version 5.25 and later of Microchip's TCP/IP Stack supports SNMP V1 and V2c formatted traps. Traps are notifications from the agent to the manager that are used when a predefined event occurs at the agent.

By default, traps are enabled in the agent. The following preprocessor macro in the TCPIPConfig.h header file can be used to disable traps in the agent:

Copy Code
#define SNMP_TRAP_DISABLED

The user must configure the expected trap format at the SNMP Manager. SNMPv2 entities acting as an agent should be able to generate and transmit SNMP V2 trap PDUs when the manager is configured to received and process SNMP V2 trap PDUs. To configure the trap format, comment or uncomment the following macro in the TCPIPConfig.h header file:

Copy Code
#defiine SNMP_STACK_USE_V2_TRAP

If the macro has been commented out, the SNMP agent will send V1 formatted trap PDUs; otherwise, it will send V2 formatted trap PDUs. By default, the SNMP agent is configured to send V2 formatted traps. Note that the SNMP V2c agent should only send V2 formatted traps.

Demos

Two trap demos are included with the TCP/IP Stack. The task functions for these demos are called in the main application function:

  • SNMPTrapDemo() - This API demonstrates V1 or V2 trap formats (depending of the status of the SNMP_STACK_USE_V2_TRAP macro). The trap PDU will only have one demo variable binding on the varbind list.
  • SNMPV2TrapDemo() - This API provides V2 format notifications with multiple (3) variable bindings. The user should modify or use this routine as a reference for sending V2 trap format notifications with multiple bindings on the varbind list.

The user should only enable one SNMP demo API at a time. By default, the SNMPTrapDemo() API is enabled and SNMPV2TrapDemo() is commented out.

V1/V2 Formatted Traps with a Single Variable Binding

In the TCPIPConfig.h header file:

  • Uncomment #define SNMP_TRAP_DISABLED
  • Comment //#define SNMP_STACK_USE_V2_TRAP

For the Trap demonstration, two events are defined within the V2c agent:

  • If the Analog Potentiometer value is greater than 512, the agent will send a Trap every 5 seconds to the configured 'trapReceiverIPAddress.'
  • If Button 3 on the demo board is pressed, an organization-specific PUSH_BUTTON trap will be sent.

The current implementation of the V2c agent also generates a standard "Authentication Failure Trap":

  • If a request is received to modify (Set) a private MIB variable, or
  • If the value of the variable is requested (get) by a browser with the wrong community name.

Procedure:

  1. Open the "Advanced" configuration menu, configure the SNMP version to '2,' and configure the Write Community to "public', 'write', or 'private'.
  2. Select the 'trapEnabled.0' variable from the MIB tree.
  3. Select 'Set' from the Operations menu.
  4. Enter '1' in the value field of the SNMP SET window.
  5. Select 'trapReceiverIPAddress.0' from the MIB tree.
  6. Set the value to the IP address of the PC on which the SNMP browser is installed and running.
  7. Select 'trapCommunity.0' from the MIB tree.
  8. Set the community name of the SNMP browser (the default community, if not set, is 'public'). The 'trapCommunity' name will work as a filter for the SNMP browsers on a trap-monitoring server.
  9. Open the "Trap Receiver' utility that was installed with the iReasoning MIB browser (Start->Programs->iReasoning->MIB Browser->Trap Receiver).

To test the analog potentiometer trap, adjust the potentiometer on the demo board so the value is greater than 512 (turn it clockwise). This is an enterprise-specific trap. The SNMP Manager will receive the source IP address, the OID (as the name of the variable), the value, the timestamp, etc. for each event. The browser will interpret the data as AnalogPot variable information based on the OID name.

To test the push button trap, press the appropriate button on the development board (RB0 on the PICDEM.net 2 or S3 on the Explorer 16 board).

To test the Authentication Failure trap, configure the Read Community in your browser to a community name that is not supported by the agent (the default supported names are 'public' and 'read'). For example:

  1. Configure 'mchp' as the Read Community name in the browser.
  2. Select the private MIB variable LED5 from the MIB tree and issue a 'Get' operation from the browser.

The result table of the browser won't display any result, but the Trap Receiver will receive and Authentication Failure trap.

This is an intimation from the agent to the SNMP Manager that there was an unauthorized attempt to access the private MIB variable in the database.

V2 Formatted Traps with a Multiple Variable Bindings

In the TCPIPConfig.h header file:

  • Uncomment #define SNMP_TRAP_DISABLED
  • Uncomment #define SNMP_STACK_USE_V2_TRAP

The SNMP V2 Trap PDU structure is:

Version (2) | community | SNMP-PDU pdu-type (TRAP=0xA7) | request-id | error-status | err-index | varbind List

The first two variable varbinds in the variable binding list of an SNMPv2-TRAP-PDU are sysUpTime.0 and snmpTrapOID.0, respectively. If any additional variables are to be included, then each of these varbind structures must be copied to the variable binding list.

For the SNMPv2 multiple TRAP variable varbind demonstration, ANALOG_POT0 is used to generate an event and transmit an SNMP v2 Trap PDU. Adjust the analog potentiometer to a value greater than 512 (turn it clockwise) on the demo board. In addition to the sysUpTime.0 and snmpTrapOID.0 varbinds, the additional varbinds that are included with the trap PDU are:

  • PUSH-BUTTON
  • LED0_IO
  • ANALOG_POT0

The following figure shows a V2 formatted trap with ANALOG_POT0 as the variable binding to be notified.

The next figure shows a multiple-variable varbind for an SNMP V2 Trap PDU, with the three additional variable bindings:

Module

Network Management (SNMP) Server

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > SNMP Traps


HTTP Configuration

Contents | Index | Home
Previous | Up | Next
HTTP Configuration

If an HTTP2 server is used with the Microchip TCP/IP Stack, it is possible to dynamically configure the Read and Write community names through the SNMP Configuration web page. Follow the steps in the Getting Started section to upload the web pages to non-volatile memory, then access the SNMP Configuration web page through the navigation bar. Use "admin" for the username and "microchip" for the password.

Module

Network Management (SNMP) Server

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > HTTP Configuration


Functions

Contents | Index | Home
Previous | Up | Next
Functions
Functions
Name | Description
SendNotification | Prepare, validate remote node which will receive trap and send trap pdu.
SNMPGetTimeStamp | Obtains the current Tick value for the SNMP time stamp.
Module

Network Management (SNMP) Server

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Functions


SendNotification Function

Contents | Index | Home
Previous | Up | Next
SendNotification Function
C
static BOOL SendNotification(
    BYTE receiverIndex,
    SNMP_ID var,
    SNMP_VAL val,
    UINT8 targetIndex
);
Description

This routine prepares the trap notification pdu, sends ARP and get remote device MAC address to which notification to sent, sends the notification. Notofication state machine is getting updated if there is any ARP resolution failure for a perticular trap destination address.

Preconditions

SNMPTrapDemo() is called.

Parameters
Parameters | Description
receiverIndex | The index to array where remote ip address is stored.
var | SNMP var ID that is to be used in notification
val | Value of var. Only value of BYTE, WORD or DWORD can be sent.
targetIndex | snmpv3 target index
Return Values
Return Values | Description
TRUE | If notification send is successful.
FALSE | If send notification failed.
Remarks

None.

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Functions > SendNotification Function


SNMPGetTimeStamp Function

Contents | Index | Home
Previous | Up | Next
SNMPGetTimeStamp Function
C
static DWORD SNMPGetTimeStamp();
Description

This function retrieves the absolute time measurements for SNMP time stamp.Use TickGet and TickGetDiv64K to collect all 48bits of the internal Tick Timer.

Preconditions

None

Return Values
Return Values | Description
timeStamp | DWORD timevalue
Remarks

None.

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Functions > SNMPGetTimeStamp Function


Variables

Contents | Index | Home
Previous | Up | Next
Variables
Module

Network Management (SNMP) Server

Variables
Name | Description
gSendTrapSMstate | This is variable gSendTrapSMstate.
gSnmpNonMibRecInfo | OLD snmp.mib file with SMIv1 standard
gSnmpv3UserSecurityName | This is variable gSnmpv3UserSecurityName.
Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Variables


gSendTrapSMstate Variable

Contents | Index | Home
Previous | Up | Next
gSendTrapSMstate Variable
C
UINT8 gSendTrapSMstate = 0;
Description

This is variable gSendTrapSMstate.

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Variables > gSendTrapSMstate Variable


gSnmpNonMibRecInfo Variable

Contents | Index | Home
Previous | Up | Next
gSnmpNonMibRecInfo Variable
C
SNMPNONMIBRECDINFO gSnmpNonMibRecInfo[SNMP_MAX_NON_REC_ID_OID] = { {{43,6,1,4,1,0x81,0x85,0x47,6},SNMP_V3}, {{43,6,1,2,1,1},SNMP_V2C}, {{43,6,1,4,1,0x81,0x85,0x47,0x1},SNMP_V2C}, };
Description

OLD snmp.mib file with SMIv1 standard

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Variables > gSnmpNonMibRecInfo Variable


gSnmpv3UserSecurityName Variable

Contents | Index | Home
Previous | Up | Next
gSnmpv3UserSecurityName Variable
C
BYTE gSnmpv3UserSecurityName[USER_SECURITY_NAME_LEN];
Description

This is variable gSnmpv3UserSecurityName.

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Variables > gSnmpv3UserSecurityName Variable


Macros

Contents | Index | Home
Previous | Up | Next
Macros
Macros
Name | Description
MAX_TRY_TO_SEND_TRAP |
SNMP_MAX_NON_REC_ID_OID | Update the Non record id OID value which is part of CustomSnmpDemo.c file
STACK_USE_SMIV2 | Default STACK_USE_SMIV2 is enabled . For Stack V5.31, STACK_USE_SMIV2 should be disabled.
Module

Network Management (SNMP) Server

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Macros


MAX_TRY_TO_SEND_TRAP Macro

Contents | Index | Home
Previous | Up | Next
MAX_TRY_TO_SEND_TRAP Macro
C
#define MAX_TRY_TO_SEND_TRAP (10)
Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Macros > MAX_TRY_TO_SEND_TRAP Macro


SNMP_MAX_NON_REC_ID_OID Macro

Contents | Index | Home
Previous | Up | Next
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

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Macros > SNMP_MAX_NON_REC_ID_OID Macro


STACK_USE_SMIV2 Macro

Contents | Index | Home
Previous | Up | Next
STACK_USE_SMIV2 Macro
C
#define STACK_USE_SMIV2
Description

Default STACK_USE_SMIV2 is enabled . For Stack V5.31, STACK_USE_SMIV2 should be disabled.

Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server > Macros > STACK_USE_SMIV2 Macro


UART-to-TCP Bridge

Contents | Index | Home
Previous | Up | Next
UART-to-TCP Bridge

Overview

The UART-to-TCP bridge feature of the TCP/IP Demo App transmits all incoming TCP bytes on a socket out of the PIC's UART module and all incoming UART bytes out of a TCP socket.

Instructions

  1. Compile your MPLAB project and program the demo board.
  2. Connect the RS-232 port on your demo board to an RS-232 port on your computer. On a newer computer you may need an RS-232 to USB converter cable. On your computer, open a terminal program (such as HyperTerminal). Set it to use the COM port you connected your board to, at 19200 baud, with 8 data bits, no parity, 1 stop bit, and no flow control.
  3. Connect the programmed demo board to a computer either directly or through a router. For Ethernet, a direct connection may require a crossover cable; for WiFi, the board may need to be in AdHoc mode to establish a direct connection.
  4. Determine the IP address of the demo board. This can be done several different ways.
    1. If you are using a demo setup with an LCD display (e.g. Explorer 16 or PICDEM.net 2), the IP address should be displayed on the second line of the display.
    2. Open the Microchip Ethernet Device Discoverer from the start menu. Press the "Discover Devices" button to see the addresses and host names of all devices with the Announce Protocol enabled on your network. You may have to configure your computer's firewall to prevent it from blocking UDP port 30303 for this solution.
    3. If your board is connected directly with your computer with a crossover cable:
      1. Open a command/DOS prompt and type 'ipconfig'. Find the network adaptor that is connected to the board. The IP address of the board is located in the 'Default Gateway' field
      2. Open up the network status for the network adaptor that connects the two devices. This can be done by right clicking on the network connection icon in the network settings folder and select 'status' from the menu. Find the 'Default Gateway' field.
  5. Open a command/DOS prompt. Type "telnet ip_address 9761" where ip_address is the IP address that you got from step 4.

  6. As you type characters in the command prompt, they will be transmitted over the Telnet TCP port to the PIC, and then transmitted out of the PIC's UART to appear on your terminal program. As you type characters in the terminal program, they will be transmitted to the PIC through the UART module, and then retransmitted over the TCP connection to appear in the command prompt Telnet session.

Demo Information > Available Demos > Demo App > Demo Modules > UART-to-TCP Bridge


Zero Configuration (ZeroConf)

Contents | Index | Home
Previous | Up | Next
Zero Configuration (ZeroConf)

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.

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 WiFi demo applications (and the MRF24WB0M module). Future versions of the stack should enable Zeroconf support across all Ethernet solutions.

Link Local

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.

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).

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.

Demo

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.

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.

Demo Information > Available Demos > Demo App > Demo Modules > Zero Configuration (ZeroConf)


Internet Bootloader

Contents | Index | Home
Previous | Up | Next
Internet Bootloader

The Internet Bootloader is a stand alone application allowing new application firmware to be uploaded directly into the Flash memory of a PIC18F microcontroller over an Ethernet network or the Internet. For other PIC and dsPIC architectures, third-party TCP/IP bootloaders can be obtained from [image] http://www.brushelectronics.com/. This Internet Bootloader application implements its own private UDP/IP stack as well as a Trivial File Transfer Protocol (TFTP) server. The bootloader operates independently of the main application and cannot update itself. Safeguards are implemented internally to minimize the risk of non-recoverable failed upgrades.

Important attributes of the Internet bootloader include:

  • Self contained TFTP, UDP, IP, ARP, and Ethernet protocol handling
  • Executes on Power-on Reset instead of during main application
  • Waits approximately 4 seconds before starting main application
  • Requires 8KB of program Flash
  • Requires 0B of RAM (all used RAM is overlaid with main application)
  • Requires no CPU time while executing main application
  • Requires minimal or no changes to main application code and linker script
  • Does not interfere with application interrupt vector locations or add interrupt latency
  • Can reprogram configuration words
  • Can reuse MAC and IP address provided by main application
  • Client update software is already available on most computers
Topics
Name | Description
Bootloader Design | Describes the design and theory of operation for the bootloader
Using the Bootloader | Describes two methods for using the bootloader.
Demo Information > Available Demos > Internet Bootloader


Bootloader Design

Contents | Index | Home
Previous | Up | Next
Bootloader Design
Bootloader Entry

The bootloader is a TFTP server which starts automatically on Power-on Reset (POR). It can be located anywhere within program memory. To cause the automatic startup, the bootloader transparently performs a replacement of the instruction(s) at program memory locations 000000h-000003h. The .hex file to be programmed to the chip by the bootloader will normally contain a GOTO instruction at address 000000h which branches to the main application. Instead of writing the original instruction at address zero, the bootloader creates a new GOTO instruction which always branches to the start address of the bootloader code. The original application instruction at address zero is moved to a jump table, which is later called to exit the bootloader. The jump table also contains a GOTO 000004h instruction to ensure normal application operation if the first instruction was not a GOTO.

If the device is programmed with only the bootloader (no application), address 000000h through the start address of the bootloader code will be in an unprogrammed state (FFFFh). These are NOP instructions which will quickly execute until the program counter reaches the start of the bootloader. This ensures entry into the bootloader for both programmed and unprogrammed parts.

Bootloader Re-entry

If the running application wants to reenter the bootloader, it should clear the RCON<NOT_POR> bit and then execute a RESET instruction. When the bootloader returns control to the main application, the NOT_POR bit will be in the set state. If an application needs to reset quickly without waiting for the bootloader timeout, it should leave this bit in the set state. This will cause the bootloader to skip its normal operation and return immediately to the application.

Prior to executing the RESET instruction to reenter the bootloader, the main application can specify the MAC and IP address for the bootloader to use. To do this:

  1. Select a random memory location where 12 bytes can be written
  2. Copy the MAC address to the chosen memory location at offset 0
  3. Copy the IP address to the chosen memory location at offset 6
  4. Compute an IP checksum of the MAC and IP address stored at the memory locations 0 through 9
  5. Write the IP checksum at the chosen memory location at offset 10
  6. Store the address of the chosen memory location into the PRODH:PRODL registers
  7. Clear the RCON<NOT_POR> bit and execute a RESET instruction to enter the bootloader

Upon entry, the bootloader will detect that the RCON<NOT_RI> bit is clear, indicating the bootloader was entered from the main application instead of a genuine POR event. In this case, the bootloader will dereference the PRODH:PRODL pointer, validate the checksum, and if valid, use the MAC and IP address specified. If the checksum is invalid, the bootloader will use it's default compiled MAC and IP address.

The Microchip TCP/IP Stack library provides a Reboot module which can perform the above procedure upon detection of a TFTP packet. When the Reboot module is used, the application IP address (possibly obtained automatically via DHCP) can be used as the TFTP bootloader target. If the IP address used by the main application is Internet routable, then the bootloader itself will be accessible via the Internet.

Memory Map

The entire program memory map when using the bootloader is shown below.

*: GOTO instruction is automatically generated by bootloader when writing. Application instruction at address 000000h is moved to Bootloader Jump Table.

**: Some configuration options are not supported and will automatically be changed by the bootloader before flashing. The bootloader requires HS or HS+PLL oscillator mode and does not support 1:1 and 1:2 Watchdog Timer Postscale modes. Switching between Extended and non-Extended mode is not supported either. (The bootloader must be recompiled to change modes.)

The bootloader uses a block of 8256 bytes of program memory. To prevent the application from inadvertently using this block, you should modify the linker script in your application prior to compiling. For example, for the MPLAB® C18 C compiler, the linker script will contain a CODEPAGE line describing the available Flash memory in the device. For the PIC18F97J60 product with 128kB of program memory, the linker script (18f97j60i.lkr) will contain a line such as:

CODEPAGE NAME=page START=0x2A END=0x1FFF7

This line indicates that the linker can place application constants and code anywhere between 00002Ah and 01FFF7h. This line must be split into two CODEPAGE lines to describe the gap in available program memory occupied by the bootloader. Ex:

CODEPAGE NAME=page START=0x2A END=0x1DBBF

CODEPAGE NAME=page2 START=0x1FC00 END=0x1FFF7

The above example removes the Jump Table and Bootloader Code blocks for the PIC18F97J60 with 128kB of Flash memory. Other devices with less Flash memory will need to use different start and end values according to the Jump Table start address and Bootloader Code end address described in the memory map figure above.

Erase Operations

The TFTP server performs a "bulk erase" before starting any TFTP put (write) operation. The erase is not a true bulk erase because the bootloader and configuration words remain intact. However, all other locations are reverted to their unprogrammed state. The erase procedure starts with the Flash page containing the Jump Table and continues backwards in memory towards address 000000h. After address 000000h is erased, the last program memory page containing the device configuration words is erased. For example, assuming a PIC18F97J60 with 128kB of Flash, the erase procedure will follow these steps:

  1. Erase 01D800h-01DBFFh
  2. Erase 01D400h-01D7FFh
  3. Erase 01D000h-01D3FFh
  4. ...
  5. Erase 000400h-0007FFh
  6. Erase 000000h-0003FFh
  7. Erase 01FC00h-01FFFFh

After the last page containing the configuration words are erased, the configuration words are immediately reprogrammed to their previous value. This algorithm provides very robust operation with an extremely low likelihood of destroying access to the bootloader due to an unexpected event (ex: power or network connectivity is lost while bootloading). Unexpected events will leave the first GOTO instruction at address 000000h intact, ensuring that the bootloader will start up again. Because the configuration words are erased last, there will not be any means of circumventing the internal code protect feature while application code still remains in the device.

Program Operations

Program operations are performed sequentially starting at address 000000h and growing upwards, as presented in the .hex file to be programmed. The device configuration words are typically the last values encountered in the .hex file. Because the erase procedure involves clearing the configuration words and then immediately reprogramming them, the configuration words will already be programmed by the time the configuration words are encountered in the .hex file. Therefore, if the .hex file contains different configuration words from what are already stored in the Flash memory, the bootloader will have to perform a new erase operation on the last page prior to programming the new configuration words. This extra erase/write cycle will reduce overall Flash endurance on the last page as compared to the rest of the device. However, the bootloader will not perform this erase/write if the configuration words have not changed. This feature preserves endurance for most application firmware upgrades, which typically do not require different configuration options to be programmed.

Read Operations

To save code space, the bootloader currently only supports reading through the TFTP server as binary data. Instead of getting a .hex file from a TFTP get operation, the bootloader will send back a binary file sized to the amount of internal Flash memory available (128kB for PIC18F97J60, 64kB for PIC18F66J60, etc.). The bootloader verifies code immediately after programming devices, so the read feature is primarily for debugging only.

Read operations are disabled if the currently programmed application has the PIC® microcontroller Code Protect feature turned on.

Demo Information > Available Demos > Internet Bootloader > Bootloader Design


Using the Bootloader

Contents | Index | Home
Previous | Up | Next
Using the Bootloader
Operation

After the bootloader has started, the code will enable the Ethernet module and begin running a private UDP/IP stack. It will use the following default addresses out of Power-on Reset:

  • IP Address: 192.168.97.60
  • MAC Address: 00-04-A3-00-00-00

These default addresses are statically defined and can only be changed by recompiling the bootloader itself. However, if the bootloader is called from the main application, such as with the Reboot module, then the bootloader will use the application assigned IP and MAC addresses (if provided).

The only services that are available during bootloader operation are TFTP and ARP. ICMP (ping) and other services are not implemented.

Configuring Your PC (Power-on Reset entry)

To access the bootloader, the bootloader's IP address must be on the same subnet as your computer. For the default 192.168.97.60 IP address, you must temporarily change the settings on your PC. If the bootloader's IP address was application specified and already on the same subnet as your PC, then this section should be skipped.

The following instructions assume you are using Microsoft® Windows® XP and will vary for other operating systems.

  1. Open Network Connections.
  2. Right click on the network adapter that you are using to communicate with the bootloader and choose Properties.
  3. Select Internet Protocol (TCP/IP) and click Properties.
  4. Select Use the following IP address and then enter the IP address 192.168.97.61.
  5. Click OK and then Close on the previous dialog to close them and set the new address.

TFTP Operation (Power-on Reset entry)

Most operating systems come with a TFTP client built in. In Microsoft Windows, this utility is named tftp.exe. This utility is a very simple console application which can be used to upload your application .hex file over the network to the bootloader. To perform a Flash upgrade using the tftp.exe client, follow these procedures:

  1. At a console, type the following command, but do not execute it. Make appropriate path changes to the .hex file. tftp 192.168.97.60 put "C:\Microchip Solutions\TCPIP Demo App\TCPIP Demo App-C18.hex"
  2. Power cycle the target board or if the device has a MCLR reset button, press it.
  3. Quickly press enter to execute the tftp command. If firmware is already in the device, the bootloader will automatically terminate after approximately 4 seconds, so you must execute the tftp command within the 4 second window.
  4. If successful, the TFTP client will indicate how long the transfer took. Actual programming time will vary based on numerous factors, including need to erase the Flash first, .hex file size, .hex file complexity, and internal programming time. The reported transfer rate is therefore not a good metric of network performance in embedded applications.

    The bootloader does data read back verification shortly after writing and does not need a second step to read back the Flash contents. If a verification error occurs, the error will be immediately reported to the TFTP client.

    The most likely cause of a verification failure is not a Flash endurance problem, but rather, an invalid .hex file given as input. As shown in the bootloader memory map, .hex files cannot contain any data within the 8KB area of Flash were the bootloader is stored. The bootloader internally masks off this region of Flash and treats it as read only to prevent bootloader corruption. As a result, if the .hex file contains data in the read-only region, the write will fail and verification will show a mismatch.
  5. After a successful write, the bootloader will time out after approximately 4 seconds and begin executing the main application that was just loaded.

After completing the TFTP upload process, restore your PC's IP address settings to allow normal network activity and access to the application you bootloaded.

TFTP Operation (Application entry)

If using an application which auto-detects TFTP packets and enters the bootloader as needed, such as the Reboot module in the Microchip TCP/IP Stack, then there will generally be no need to reconfigure your PC or go through a time-sensitive power cycling process. Instead, you can execute a TFTP operation directly on the device without any interactive steps.

  1. At a console, type the following command and execute it. Make appropriate IP adddress/hostname and path changes.

tftp mchpboard put "C:\Microchip Solutions\TCPIP Demo App\TCPIP Demo App-C18.hex"

If the bootload process is interrupted due to a network failure or user cancellation, you can simply retry the tftp command. The bootloader will not attempt to run a partially bootloaded application. The application specified MAC and IP address will be retained indefinitely until the device is power cycled or otherwise reset.

If the bootload operation is interrupted due to a power failure, the bootloader will start back up using the Power-on Reset default MAC and IP addresses. In this case, you must follow the Power-on Reset entry directions to recover.

Demo Information > Available Demos > Internet Bootloader > Using the Bootloader


WebVend

Contents | Index | Home
Previous | Up | Next
WebVend

The TCPIP WebVend App is a sample web-enabled vending machine application. It is used by the TCP/IP Webinar series:

  1. TCP/IP Networking Part 1: Web-Based Status Monitoring ( [image] view)
  2. TCP/IP Networking Part 2: Web-Based Control ( [image] view)
  3. TCP/IP Networking Part 3: Advanced Web-Based Control ( [image] view)
Demo Information > Available Demos > WebVend


Internet Radio

Contents | Index | Home
Previous | Up | Next
Internet Radio

IMPORTANT: Because of changes to the SHOUTcast protocol, the Internet Radio demo app is no longer able to perform its intended function. This demo now exists only as an TCP/IP Stack code example.

The Internet Radio app demonstrates the use of the TCP/IP Stack for a stand-alone embedded application. This application is capable of contacting various [image] SHOUTcast servers and playing back the audio stream to a pair of stereo speakers. The demo requires the Internet Radio Demonstration board. A PIC18F67J60 is used for the processing of Ethernet interface, while an external MP3 decoder handles the audio playback. Application note [image] AN1128 "TCP/IP Networking: Internet Radio Using OLED Display and MP3 Audio Decoder (DS01128)" describes the Internet Radio application in detail.

To run the demo, first make sure the Internet Radio board has the correct firmware programmed. Next, connect the board to the internet, plug in an audio headset or speaker. By default, the program will not play a radio station automatically until a genre is selected. Follow the OLED display’s on screen menu to change genre, station, and volume.

The board can also be controlled via the web browser interface. To connect to the board’s web server, use the IP address shown on the board’s OLED display. Shown below is a screen shot of the webpage. To start, first select a genre from the drop down list box, and click 'Select'. To change station, click 'Prev' or 'Next'. To adjust volume, click 'Down' or 'Up'. If a station does not play, it could be that the port is blocked, try a different station.

Each Internet Radio board also has a sticker containing a unique MAC address. This unique MAC address can be saved to the board by using the web interface’s configurations section.

Demo Information > Available Demos > Internet Radio


WiFi Console

Contents | Index | Home
Previous | Up | Next
WiFi Console

The TCPIP WiFi Console Demo App (previously the TCPIP WiFi Iperf Demo App) is a command line interface (CLI) to the MRF24WB0M. It allows for command line debugging and setup of network information for the wireless LAN. It also has iperf built in for doing WLAN bandwidth testing. This application is meant more as a development debug tool, and should be disabled in end user applications.

Topics
Name | Description
Standalone Commands | Standalone CLI commands for talking with the MRF24WB0M.
iwconfig Commands | Commands for controlling the wireless network interface.
ifconfig Commands | Commands for controlling the network interface.
iwpriv Commands | Commands for controlling the wireless encryption settings.
iperf Example | An example of using iperf to measure network bandwidth and performance.
Demo Information > Available Demos > WiFi Console


Standalone Commands

Contents | Index | Home
Previous | Up | Next
Standalone Commands

These CLI commands are not related to the wireless or networking interface directly.

help |
 | Lists all the available CLI commands for the MRF24WB0M.
getwfver |
 | Lists the WiFi firmware and host driver version numbers.
reset |
 | Issues a host reset.
cls |
 | Resets the prompt.
kill iperf |
 | Kills a running iperf session. See the section on iperf for more information.
Demo Information > Available Demos > WiFi Console > Standalone Commands


iwconfig Commands

Contents | Index | Home
Previous | Up | Next
iwconfig Commands

Note that most of these items should not be changed while the device is in a connected state to a network.

iwconfig commands take the following structure:

iwconfig
[ ssid <name> ]
[ mode <idle|managed|adhoc> ]
[ channel <channel list|all> ]
[ power <reenable|disable|unicast|all> ]
[ domain <name> ]
[ rts <length> ]
[ txrate <0|1|2> ]
[ scan ]
[ hibernate ]
[ wakeup ]

Note: iwconfig with no options will display wireless status.

ssid |
name | 1-32 ASCII characters. Currently doesn't accept spaces in the SSID name.
mode |
idle | Forces the MRF24WB0M to disconnect from any currently connected network (adhoc or infrastructure).
managed | The MRF24WB0M will connect to the SSID in infrastructure mode. Note that all the network parameters must be correct before this command is called.
adhoc | The MRF24WB0M will connect to the SSID in adhoc mode. Note that all the network parameters must be correct before this command is called.
channel |
channel list | A comma separated list of all the channels to scan.
all | Sets the MRF24WB0M to scan all channels in the given regulatory domain.
power |
reenable | Enables all power saving features (PS_POLL) of the MRF24WB0M.
disable | Disables any power savings features. The MRF24WB0M will always be in an active power state.
unicast | The MRF24WB0M will be in it's deepest sleep state, only waking up at periodic intervals to check for unicast data. The MRF24WB0M will not wake up on the DTIM period for broadcast or multicast traffic.
all | The MRF24WB0M will wake up to check for all types of traffic (unicast, multicast, and broadcast).
domain |
fcc | United States channels 1-11.
ic | Canada channels 1-11.
etsi | European channels 1-13.
spain | Spanish channels 10-11.
france | French channels 10-13.
japana | Japanese channel 14.
japanb | Japanese channels 1-11.
rts |
length | Set the requested number of bytes to send. Default max is 2347.
txrate |
0 | The MRF24WB0M will do automatic rate adaptation between 1 and 2 Mbps.
1 | Sets the MRF24WB0M to fixed data rate of 1Mbps.
2 | Sets the MRF24WB0M to fixed data rate of 2Mbps.
scan |
 | Instructs the MRF24WB0M to perform an active site scan. Scan results will be displayed to the output terminal.
hibernate |
 | Removes power to the MRF24WB0M.
wakeup |
 | Restores power to the MRF24WB0M and reconnects.

Note: scan is only supported by the WiFi EZConfig demo.

Demo Information > Available Demos > WiFi Console > iwconfig Commands


ifconfig Commands

Contents | Index | Home
Previous | Up | Next
ifconfig Commands

Note that these items should not be changed while the device is in a connected state to a network.

ifconfig commands take the following structure:

ifconfig
[ <IP address> ]
[ <MAC address> ]
[ netmask <IP address> ]
[ gateway <IP address> ]
[ auto-dhcp <start|drop> ]

Note ifconfig by itself will give network status.

IP address |
 | Use a static IP address. IP address must be in dot-decimal notation. Note that this command will return an invalid parameter if the DHCP client is enabled. First disable the DHCP attempts (ifconfig auto-dhcp drop) before running this command.
MAC address |
 | Redefine the device MAC address. MAC address must be specified in hexadecimal colon notation. This command can only be issued when the MRF24WB0M is in idle mode. Doing so at other times can have unexpected results.
netmask |
IP address | Use the specified IP address for the netmask. The netmask value is specified in dot-decimal notation.
gateway |
IP address | Configure the gateway address. The gateway value is specified in dot-decimal notation.
auto-dhcp |
start | Starts the DHCP client. Only valid if the DHCP module has been compiled in. DHCP client is started by default.
drop | Stops the DHCP client. A static IP address will need to be assigned to the device. Only valid if the DHCP module has been compiled in.
Demo Information > Available Demos > WiFi Console > ifconfig Commands


iwpriv Commands

Contents | Index | Home
Previous | Up | Next
iwpriv Commands

Note that these items should not be changed while the device is in a connected state to a network.

iwpriv commands take the following structure:

iwpriv
[ enc <none|wep|wpa-psk|wpa-phrase> ]
[ key <[1]|[2]|[3]|[4]> <value> ]
[ psk <value> ]
[ phrase <value> ]

Note iwpriv by itself will display network security settings.

enc |
none | The MRF24WB0M will not use any encryption to connect to the specified network.
wep | The MRF24WB0M will use either WEP-40 (short) or WEP-104 (long) encryption to connect to the specified network.
wpa-psk | The MRF24WB0M will use the specified 32-byte PSK to connect to the WPA/WPA2 network.
wpa-phrase | The MRF24WB0M will take the given 1-32 ASCII character passphrase, along with the SSID, and compute the required 32-byte PSK for the network. Note that doing so takes approximately 30 seconds to complete the calculation.
key |
[1] [2] [3] [4] | Instructs the MRF24WB0M to use this key for connecting to the WEP encrypted network. Note that only key 1 is considered safe to use among different AP vendors. Keys 2-4 can have implementation specific entries that may not be compatible from AP to AP.
value | If value is specified, this will instruct the MRF24WB0M to use the specified key number and also program the device with this key value. For WEP-40 networks, this implies the key is either 5 ASCII characters of 10 hex characters in length. For WEP-104 networks, this implies the key is either 13 ASCII characters or 26 hex characters in length. The console only accepts hex WEP keys. Therefore, the user must do the ASCII to hex conversion for their ASCII keys.
psk |
value | 32-byte hex value for the PSK. This value can be calculated from the following website hosted on the [image] Wireshark website.
phrase |
value | An 8-63 ASCII character phrase (delimited with quotes if using spaces). This phrase will be used along with the SSID to generate the 32-byte PSK value for the network.
Demo Information > Available Demos > WiFi Console > iwpriv Commands


iperf Example

Contents | Index | Home
Previous | Up | Next
iperf Example

iperf is a networking tool that helps to measure networking bandwidth and performance. The console demo application has a built-in iperf application, that can act as both a client and server for testing. iperf has the ability to test both UDP and TCP. In the case of UDP, you can specify the size of the UDP datagrams. For TCP, iperf measures the throughput of the payload.

In order to run iperf, you'll need a PC that has an iperf application on it as well. There is an open source version that is maintained, as well as many other variants across the internet. iperf is meant to be run at the command line. However, if a GUI is desired, a variant called jperf can be used.

In the case of the demo application, iperf measures performance data in a unidirectional format. Therefore, the side that the server is running on is considered the receiver, and provides the most accurate performance values.

Command Synopsis
iperf
[ -s|-c <IP addr> ]
[ -u ]
[ -i <sec> ]
[ -b <bandwidth> ]
[ -t <time> ]

-s | Runs the iperf server. No IP address needs to be specified.
-c <IP addr> | Runs the iperf client. The IP address is the IP address of the server.
-u | Server side only. Sends UDP datagrams.
-i <sec> | Specified the time interval, in seconds, that the display will be updated.
-b <bandwidth> | Specifies the amount of data to try and send. This option is only valid with UDP datagrams.
-t <time> | Amount of time, in seconds, to run the test.

Running the Demo

After powering on the development board and associating with your wireless network, you'll need to start the server side iperf application first. if you start iperf as a server on the development board in the console, then this implies that you are trying to measure the MRF24WB0M receiver performance. If you start the iperf server on a PC, then you will be measuring MRF24WB0M transmit performance. Below are two images that show receiver and transmitter performance, respectively.

iperf MRF24WB0M receiver performance

iperf MRF24WB0M transmit performance

Demo Information > Available Demos > WiFi Console > iperf Example


WiFi EZConfig

Contents | Index | Home
Previous | Up | Next
WiFi EZConfig
Overview

WLAN networks provide a unique challenge for configuring embedded wireless without a natural user interface. Unlike wired networks, wireless networks require unique items such as the SSID and network type and keys, which have to be sent to the device in some form or another. Traditionally, this means a user would enter this information using a keyboard and display.

EasyConfig is a mechanism to allow for configuration of an embedded device on a wireless network. It utilizes the web server of the TCP/IP stack, as well as a wireless adhoc (IBSS) network to allow the user to input the desired network information from a client browser, and then reset the device to connect to the desired network.

The EasyConfig demo works in roughly the following manner:

  1. Upon power up the device, it broadcasts an adhoc network with SSID "EasyConfig".
  2. A client device (laptop, iPod Touch/iPhone/iPad) can then connect to the EasyConfig network.
  3. Upon connecting, the user can then use a standard web browser to go to the IP address of the demo (http://169.254.1.1).
  4. The user will then be presented with some web pages from the web server. The index.htm web page has some additional information on EasyConfig, and also shows the continually updating status of the LEDs, buttons, and potentiometer on the development board. The configure.htm page will allow the user to scan for networks, and connect to a network of their choosing.
  5. The device will then reset itself, using the parameters for the new network. In order to continue using the demo, the client device will now need to reconnect to the same network that the development board is on.

Note that the demo will always attempt to connect to the last known network. If the user wants to reset the demo to startup in adhoc mode again, then button S3 on the Explorer 16 development board needs to be held down for 4 seconds.

Adhoc Networks

Upon starting the demo, the network will either connect to another adhoc network, or will start it's own if one is not found. Adhoc networks are peer-to-peer networks, with no centralized coordinator for the network. All the devices in the network share the responsibilities of keeping the network going.

One downfall of adhoc networks is that typically security is not employed on them. The MRF24WB0M module can secure the network with WEP (40-bit/104-bit) security, as can most laptops and adhoc devices. Almost no devices in the market can secure an adhoc network with WPA level security due to the tremendous overhead in doing so.

The demo starts an adhoc network with no security. This means that all the network information that is being configured on the device is going over-the-air in the open. For most applications, unless somebody is specifically attempting to eavesdrop on this network, there should be little to no impact on security. However, for applications that do require some baseline level of security, then WEP can be employed on the network. SSL can also be used to encrypt the traffic between the web server and client browser. Additionally, some other form of data-level security can be employed to obfuscate the ASCII network information being sent to the device.

Network Parameters

Below is some information on the parameters that are being sent via HTTP POST from the client browser to the device. All this information is being parsed and handled in the function HTTPPostWifiConfig() in CustomHTTPApp.c.

WLAN Type
Either adhoc or infrastructure
SSID
Name of network (1-32 ASCII characters)
Security Type

  • None
  • WEP-40 (5 ASCII characters or 10 hex numbers)
  • WEP-104 (13 ASCII characters or 26 hex numbers)
  • WPA/WPA2 passphrase (8-63 ASCII characters)

Configured vs Un-configured State

When the demo is running in an unconfigured state (i.e, serving the default EasyConfig SSID in adhoc mode), then the heartbeat LED (LED0) will blink twice per second to indicate that it hasn't been configured yet. Once the network has been configured, then the heartbeat LED will change to blink once per second, in a similar fashion to the other TCP/IP demo applications.

EasyConfig Demo Additional Features

There are four defines that enable EasyConfig as well as extend it with natural features.

STACK_USE_EZ_CONFIG | The top level define to enable EasyConfig features.
EZ_CONFIG_SCAN | Adds additional ability to instruct the MRF24WB0M module to scan for available networks nearby. This can be done when you are already connected to a network.
EZ_CONFIG_STORE | Store the configuration information for the new network to non-volatile memory. In the event that WPA/WPA2 level security is used, the 32-byte PSK will be saved to NVM.
EZ_CONFIG_STALL | Before switching networks, forces the configuration state machine to pause. This gives the client device additional time to request resources from the development platform before it attempts to connect to a new network.

EZ_CONFIG_SCAN

The MRF24WB0M has the ability to scan for nearby networks. This is similar to a laptop that can show available wireless networks that can be connected to. The scan results are stored on the MRF24WB0M module, and can be retrieved one at a time from the device. This helps to reduce the impact of storing all the scan results on the host itself.

The scan can be performed when idle, or when connected to either an adhoc or infrastructure network.

EZ_CONFIG_STORE

The new network parameters can also be stored to non-volatile memory. For the Explorer 16 development board, this information is stored to the 32kB EEPROM on the board.

One extremely useful feature of storing the information surfaces when connecting to a network with WPA/WPA2 security. The computation of the 32-byte PSK is computationally heavy, and can take the MRF24WB0M up to 30 seconds to calculate the key. In a normal application, it would be unacceptable to have to wait 30 seconds every time the device started up before connection to the network was established.

EZ_CONFIG_STORE helps to alleviate doing the calculation each time by storing the 32-byte PSK to NVM. In doing so, there is only one 30-second hit the very first time the key is calculated only. Successive connections to the network will be significantly faster.

EZ_CONFIG_STALL

The configuration state machine that controls the network connections within EasyConfig can employ a wait state between switching networks. From an end user experience, this becomes vital. If the switch between different networks was instantaneous, a client browser would never get an indication that the HTTP session was closed after the POST information was sent. The end user would see this as a browser that was continually waiting, which would eventually timeout.

To make the switch more natural and complete, EZ_CONFIG_STALL adds additional time to allow the client to get the remaining web page information. For the demo, this includes a HTTP redirect to a page that highlights the new network information.

Current Incompatibilities

The javascript being used in EasyConfig is not compatible with Internet Explorer 7. EasyConfig does work with many other flavors of browser on different architectures, not limited to Internet Explorer 8, Mozilla Firefox, Apple Safari and Google Chrome. The incompatibility is something that is being investigated, and should be fixed in a future stack release.

Demo Information > Available Demos > WiFi EZConfig


Demo App MDD

Contents | Index | Home
Previous | Up | Next
Demo App MDD

The TCPIP MDD Demo App is a variant of TCPIP Demo App that uses an SD card or USB Thumb Drive to store web pages. For more information, see the TCPIP MDD Demo App Getting Started guide, installed in the stack's documentation folder.

Demo Information > Available Demos > Demo App MDD


Google PowerMeter

Contents | Index | Home
Previous | Up | Next
Google PowerMeter

Google, Inc. has deprecated Google PowerMeter and expressed its intent to remove access to it on September 16, 2011.

Because of this development, Microchip Technology has removed the Google PowerMeter demo projects from the Microchip Application Libraries distribution. To obtain Microchip's Google PowerMeter reference implementation, please download the archived Microchip Application Libraries installation from June, 2011 from [image] www.microchip.com/mal.

Demo Information > Available Demos > Google PowerMeter


Energy Monitoring

Contents | Index | Home
Previous | Up | Next
Energy Monitoring

This demo implements a power monitoring application that uploads data to Google PowerMeter. In this application, actual power consumption data is obtained from a PIC18F87J72 Energy Monitoring PICtail Plus Daughter Board.

Google, Inc. has deprecated Google PowerMeter and expressed its intent to remove access to it on September 16, 2011.

Because of this development, Microchip Technology has removed the Google PowerMeter demo projects from the Microchip Application Libraries distribution. To obtain Microchip's Google PowerMeter reference implementation, please download the archived Microchip Application Libraries installation from June, 2011 from www.microchip.com/mal.

This Energy Monitoring demo has been modified to remove its Google PowerMeter upload features. However, the energy measurements made by the PICtail can still be viewed on the demo board-hosted web page.

The PC GUI for the Energy Monitoring PICtail can be obtained from: http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en550456

Demo Information > Available Demos > Energy Monitoring


Using the Stack

Contents | Index | Home
Previous | Next
Using the Stack

This section describes how to use Microchip's TCP/IP Stack.

Topics
Name | Description
Stack Architecture | Describes the TCP/IP stack architecture.
How the Stack Works | Describes how the stack works and how to start creating your application.
Using the Stack


Stack Architecture

Contents | Index | Home
Previous | Up | Next
Stack Architecture

The TCP/IP stack is modular in design and written in the 'C' programming language. It follows the TCP/IP (Internet) protocol suite. The stack currently supports the TCP and UDP transport layer modules, the IPv4 (and part of the ICMP) Internet Layer modules, the ARP link layer modules, and a variety of application layer modules. Most of the Media Access Control link layer functionality is provided by the hardware MAC/PHY chips used with the stack.

Using the Stack > Stack Architecture


How the Stack Works

Contents | Index | Home
Previous | Up | Next
How the Stack Works

This topic contains information about how the stack works, what is required to use the stack, and how your code can be structured to work cohesively with the TCP/IP stack.

Topics
Name | Description
Required Files | Describes the base files needed in a TCP/IP project.
APP_CONFIG Structure | Describes the APP_CONFIG structure.
Main File | Describes how to construct the main() loop in your application.
Cooperative Multitasking | Describes how to implement a non-blocking stack task.
RTOS | Contains information about using the TCP/IP Stack in a Real-Time Operating System.
Using the Stack > How the Stack Works


Required Files

Contents | Index | Home
Previous | Up | Next
Required Files

There are several base files that must be included in every project using Microchip’s TCP/IP stack. They are:

  • A main file- this is the file with your application code in it..
  • ARP.c and ARP.h- These files are used by the stack to discover the MAC address associated with a given IP address.
  • Delay.c and Delay.h – These files are used to provide delays for some stack functions. Note that it would be best to not use these delays in your own code, as they do create blocking conditions.
  • Physical layer files – These files are used to enable a specified physical layer. More information on which files to include can be found in the Hardware Configuration section.
  • Helpers.c and Helpers.h – These files contain helper functions used for miscellaneous stack tasks.
  • IP.c and IP.h – These files provide internet layer functionality for the stack.
  • StackTsk.c and StackTsk.h – These files contain the code to initialize the stack and perform the callbacks that keep the stack going.
  • Tick.c and Tick.h – These files implement a tick timer that is used to implement some timing functionality within the stack.
  • HardwareProfile.h – This configuration file is used to set up hardware options.
  • TCPIPConfig.h – This configuration file is used to set up firmware options.
  • MAC.h – This header file provides macros and structures relating to the hardware MAC layer.
  • TCPIP.h – This is the primary include file for the stack. Your main file should include TCPIP.h.

You may choose to include additional files to support additional protocols and features. The list of protocols and their required files can be found in the Protocol Macros and Files topic in the Protocol Configuration topic.

Using the Stack > How the Stack Works > Required Files


APP_CONFIG Structure

Contents | Index | Home
Previous | Up | Next
APP_CONFIG Structure

Most of the stack-related application variables are stored in an APP_CONFIG structure. These include addresses, flags, and NBNS/SSID name strings. You will need to declare one of these structures (named "AppConfig") for your application and initialize it with the default values defined in TCPIPConfig.h. For example, you would set the bytes of the MyIPAddr field to the values of the MY_DEFAULT_IP_ADDR_BYTEn macros in TCPIPConfig.h. The InitAppConfig function in the file MainDemo.c of the TCPIP Demo App project demonstrates how to populate this structure completely. The full list of parameters in the APP_CONFIG structure is defined in the file StackTsk.h.

At the beginning of most stack demonstration applications, the code will check an EEPROM to determine if it contains a valid image of an APP_CONFIG structure. If so, it will read the image and use it to populate the AppConfig instance in the demo project. Otherwise, it will load the application variables from your statically defined values and/or configure them based on application protocols (DHCP/AutoIP). This allows a board to retain its configured settings even if the application loses power.

Using the Stack > How the Stack Works > APP_CONFIG Structure


Main File

Contents | Index | Home
Previous | Up | Next
Main File

Because there is a huge variety of ways in which you could write your application, this section will provide an outline of what your main file should contain. It also provides some description of the stack operation, and of best-practice programming techniques to prevent stack problems.

Topics
Name | Description
Initialization | Describes some basic initialization calls that should be made.
Main Loop | Describes how to construct the main loop of your application.
Using the Stack > How the Stack Works > Main File


Initialization

Contents | Index | Home
Previous | Up | Next
Initialization

You should start by initializing your hardware. This includes PPS pins, oscillators, LEDs, LCDs, any SPI or PMP modules you're using to control your hardware MAC/PHY chip, etc.

Next, call the hardware initialization functions for the library. TickInit() should be called first; it will initialize the tick timer that manages your stack timing. Then call any additional initialization functions that require hardware initialization. For example, the MPFSInit() function will need to initialize an SPI port to communicate to a memory storage device to store web pages, so it should be called now.

Once your hardware is initialized, you can begin configuring your stack. Most of the stack-related application variables are stored in the AppConfig structure. At this point, you should initialize the AppConfig structure with your default values, or provide another means of initializing the AppConfig structure.

Finally, you can initialize the stack by calling the StackInit() function. This function will automatically call the initialization functions for other firmware protocols if they have been enabled in TCPIPConfig.h (i.e. TCPInit() for the TCP protocol, HTTPInit() for HTTP2,...). After StackInit() has been called, you can call other application-specific firmware initialization functions.

Using the Stack > How the Stack Works > Main File > Initialization


Main Loop

Contents | Index | Home
Previous | Up | Next
Main Loop

Once your program has been initialized, you should enter an infinite loop which will handle your application tasks. Within this loop, there are two functions that you must call regularly: StackTask and StackApplications.

The StackTask function will perform any timed operations that the stack requires, and will handle transmission and reception of data packets. This function will also route any packets that have been received to the appropriate application protocol-level function to handle it.

The StackApplications function will call loaded application modules. For example, if an application is using an HTTP2 server, StackApplications will automatically call the HTTPServer function to process any HTTP2 tasks that are queued.

Most sub-tasks within StackTask and StackApplications are implemented as state-machine controlled cooperative multitasking functions. Since these sub-tasks consists of multiple steps (which may occur at varying times) this call-back system ensures that no single task will monopolize control of the processor.

Within this main loop, you may also want to poll for any I/O changes in your application and call any application specific tasks that you've implemented. To avoid causing buffer overflows in your hardware or protocol timing violations you should try to implement your own application tasks in callback functions with timing-based triggers. A method to do this is described in the next topic.

You must make one call to StackTask for each call of StackApplications but you aren't required to call these functions with any specific frequency. Calling StackTask too infrequently could limit your throughput, though, as each call of StackTask can retrieve one packet (at most) from the packet buffer. Similarly, application tasks that are time-dependant (like an ICMP ping response) may produce undesirable results if StackApplications is not called frequently enough.

The amount of time that the main loop takes to complete one iteration depends on several factors. If data is ready to be transmitted, or if a packet of received data was received, the StackTask function will take more time than it would otherwise. Each additional protocol included in your application will cause the main loop to take additional time as well, with the amount of time for each varying from the length of the shortest state machine state in the task to the longest.

Once your application is complete, you can set up a test case to determine the min/average/approximate maximum time that your loop will take to run. You can set your code up to use an internal timer to measure the duration of each iteration of the main loop, or you can set the code up to trigger an output pin each time the main loop completes, and use an oscilloscope to capture the network execution time. You can then provide application inputs or additional network traffic with a PC program (or other PICs) to simulate real-world operating conditions.

Using the Stack > How the Stack Works > Main File > Main Loop


Cooperative Multitasking

Contents | Index | Home
Previous | Up | Next
Cooperative Multitasking

If you implement the TCP/IP stack using a cooperative multitasking approach, you must make periodic calls to task functions to transmit/receive packets and to maintain protocol functionality. To prevent conflicts with the stack, you should write your own custom tasks in a way that will allow them to give up the processor if it's not needed. If you create a protocol or application task with multiple steps, it may be beneficial to divide them up between states. You can then use a global or static variable to track your state, and call that task function periodically to move through the state machine.

The following example contains a sample application for transferring data from a machine of some type to an external target. It includes a task function called ApplicationTask that has states to wait for button inputs, update the display, and transfer data from the machine. The functions in the example are used to represent other actions: ButtonPressDetected represents the code needed to check for an input from the user, LCDDisplay represents the code needed to update a display on the machine, SampleData gets data from the machine, DataBufferIsFull indicates that the buffer used to hold data samples needs to be sent, and TransferData is a function that writes the data to an open TCP or UDP socket. In between each of these states, the ApplicationTask function returns to the main loop, and the StackTask and StackApplications functions are called. This flow will allow the StackApplications function to maintain any module tasks. The StackTask function will periodically transmit the data from the socket buffers to its destination, which will prevent the transmit buffers from overflowing.

Copy Code
unsigned char gAppState;    // State tracking variable

int main (void)
{
    // Pseudo-initialization function
    InitializeCode();

    // Setup application state
    gAppState = STATE_DISPLAY_MENU;

    // Main Loop
    while (1)
    {
        StackTask();
        StackApplications();
        ApplicationTask();
    }
}

void ApplicationTask (void)
{
    switch (gAppState)
    {
        case STATE_DISPLAY_MENU:
            LCDDisplay (stringMainMenu);
            gAppState = STATE_MAIN_MENU;
            break;
        case STATE_MAIN_MENU:
            if (ButtonPressDetected (BUTTON_1) )    // Check an input
                gAppState = STATE_MONITOR_MACHINERY;
            break;
        case STATE_MONITOR_MACHINERY:
            LCDDisplay (stringTransferringData);
            // Generate or send data
            if (DataBufferIsFull())
            {
                TransferData();
            }
            else
            {
                SampleData();
            }
            if (ButtonPressDetected (BACK_BUTTON) )
                gAppState = STATE_DISPLAY_MENU;
            break;
    }
}

Some of the states in your application may be time based. Suppose, for example, that our sample application needs to send data for 5 seconds every time an input is detected. Stack problems could occur if the application used a delay loop to wait for 5 seconds until it was time to stop, so this functionality should be implemented using the stack's built-in tick timer. When the request to send data is received, the code will get the current tick time using the TickGet function, add enough ticks to make up 5 seconds, save it in a static variable called tickCounter, and then switch to a transmit state. Every time the ApplicationTask function gets called, it will enter this state in the state machine, call TickGet again, and then compare it to the value stored in that static variable. If the current time is later than the initial time plus the delay, the code will restore the display and re-enter the main menu state.

void ApplicationTask (void)
{
    static DWORD tickCounter;
    switch (gAppState)
    {
        case STATE_DISPLAY_MENU:
            LCDDisplay (stringMainMenu);
            gAppState = STATE_MAIN_MENU;
            break;
        case STATE_MAIN_MENU:
            if (ButtonPressDetected (BUTTON_1) )    // Check an input
                gAppState = STATE_MONITOR_MACHINERY;
            break;
        case STATE_MONITOR_MACHINERY:
            LCDDisplay (stringTransferringData);
            // Save the current time, and add 5 seconds to it
            tickCounter = TickGet() + (5 * TICK_SECOND);
            gAppState = STATE_CONTINUE_MONITORING;
            break;
        case STATE_CONTINUE_MONITORING:
            if ((long)(TickGet() - tickCounter) > 0)
                gAppState = STATE_DISPLAY_MENU;
            else
            {
                // Generate or send data
                if (DataBufferIsFull())
                {
                    TransferData();
                }
                else
                {
                    SampleData();
                }
            }
            break;
    }
}

There are three tick timing macros declared to help with delays: TICK_SECOND defines the number of ticks in a second, TICK_MINUTE defines the number of ticks in a minute, and TICK_HOUR defines the number of ticks in an hour. By using the tick timer to implement delays, you can ensure that your code won't block critical functions for too long.

Using the Stack > How the Stack Works > Cooperative Multitasking


RTOS

Contents | Index | Home
Previous | Up | Next
RTOS

As an alternative to implementing your stack application in a cooperative multitasking format, you can integrate the stack into a Real-Time Operating System. For more information, see [image] Application Note 1264 on the Microchip web site.

Using the Stack > How the Stack Works > RTOS


Configuring the Stack

Contents | Index | Home
Previous | Next
Configuring the Stack

There is a wide range of configuration options available for Microchip's TCP/IP Stack. This topic will discuss the functionality of these options, and how to implement them.

Topics
Name | Description
Hardware Configuration | Describes how to configure the hardware options for your project.
Address | Describes how to set up addressing for your device.
Protocol Configuration | Describes how to set up protocols for your application.
Configuring the Stack


Hardware Configuration

Contents | Index | Home
Previous | Up | Next
Hardware Configuration

Most hardware configuration is performed by commenting, uncommenting, or defining a series of macros in the one of the variants of the header file HardwareProfile.h. You can see sample versions of how to set these options in the copies of HardwareProfile.h that are included with the stack's demo projects.

In most cases, the macro to enable a device is the same macro used to define the device's chip select pin. In the default copies of HardwareProfile.h included with the demonstration projects, there are example sections defined for most demo boards, delimited by preprocessor statements. For example, the section for the Explorer 16 begins with the macro "#elif defined (EXPLORER_16)" and continues until the next demo board preprocessor statement. If you use one of these files as a base for your project, make sure you are modifying the macros in the correct section.

Topics
Name | Description
Clock Frequency | Describes how to configure the clock for your application.
External Storage | Describes how to configure external storage options to hold web pages or structures in your application.
ENC28J60 Config | Describes how to configure your project to use an ENC28J60.
ENCX24J600 Config | Describes how to configure your project to use an ENCX24J600.
PIC18F97J60 Config | Describes how to configure your project to use a PIC18F97J60.
PIC32MX7XX Config | Describes how to configure your project to use a PIC32MX795 family part.
Configuring the Stack > Hardware Configuration


Clock Frequency

Contents | Index | Home
Previous | Up | Next
Clock Frequency

Many TCP/IP operations are time-dependant. By specifying the oscillator frequency that you're using in your application for the stack, you can enable automatic handling of these operations. To set hte clock value, substitute your oscillator frequency (in Hertz) for the value in the following macro in HardwareProfile.h:

Copy Code
#define GetSystemClock()    xxxxxxxxxxxxxxx

There are also two other clock macros. GetInstructionClock() and GetPeripheralClock() provide frequency values for the instruction clock and peripheral clock in your microcontroller. These values will usually be set as a fraction of the system clock (i.e. GetInstructionClock() would be defines as (GetSystemClock() / 2) for PIC24F processors).

Configuring the Stack > Hardware Configuration > Clock Frequency


External Storage

Contents | Index | Home
Previous | Up | Next
External Storage

There are several features in the TCP/IP stack that use external storage to maintain structures or web pages. Support for a few storage devices is included with the stack; the support files can be used as a template to write drivers for other devices as well. The HardwareProfile.h pin definitions are roughly equivalent for each storage device, except for the first word of the macro, which indicates which type of storage device it applies to (e.g. EEPROM_CS_IO vs SPIFLASH_CS_IO). There are three different storage media.

EEPROM

A EEPROM can be used to store MPFS2 web page images and custom application structures. To indicate to the stack that it should use a EEPROM to store MPFS2 images, define the macro MPFS_USE_EEPROM in the TCPIPConfig.h header file. By default, the stack includes a driver for Microchip’s 25LC256 EEPROM family (to use the 1 Mbit EEPROM, you must also define the macro USE_EEPROM_25LC1024 in TCPIPConfig.h). The macros to control communication with the EEPROM will be prepended with the string EEPROM_ in this case. To enable communication, define EEPROM_CS_TRIS and include the files SPIEEPROM.c and XEEPROM.h in your application. These files may requires some changes to support additional EEPROM devices.

Serial Flash

Storage for MPFS images and custom structures is also available on serial flash devices (tested with SST 25VF016B and Spansion 25FL040A). To indicate that the stack should use serial flash to store web pages, define MPFS_USE_SPI_FLASH in TCPIPConfig.h. The communicaiton macros will be prepended with the string SPIFLASH_ in this case. To enable communication functionality, define SPIFLASH_CS_TRIS and include the files SPIFlash.c and SPIFlash.h in your application. These files may require some changes to support additional flash devices. There are several macros included within “SPIFlash.h” that must also be defined, including macros to define the sector and page sizes, and macros to describe whether the SST or Spansion flash device is being used.

SRAM

A serial RAM can be used to store FIFO blocks and TCP Control Blocks for sockets (tested with AMT Semiconductor’s N256S0830HDA). The macros will be prepended with the string SPIRAM_ in this case. To use this functionality, define EEPROM_CS_TRIS and include the files “SPIRAM.c” and “SPIRAM.h” in your application. These files may require some changes to support additional RAM devices.

Macro | Purpose | Sample Value
xxxxxx_CS_IO | Defines the LAT (or PORT, where applicable) register bit that corresponds to the chip select pin. Defining this macro will indicate that the stack should use the specified type of external storage. | LATDbits.LATD12
xxxxxx_CS_TRIS | Defines the TRIS bit that corresponds to the chip select pin on the device. | TRISDbits.TRISD12
xxxxxx_SCK_TRIS | Defines the TRIS bit that corresponds to the clock pin of the SPI module connected to the device. | TRISGbits.TRISG6
xxxxxx_SDI_TRIS | Defines the TRIS bit that corresponds to the data-in pin of the SPI module connected to the device. | TRISGbits.TRISG7
xxxxxx_SDO_TRIS | Defines the TRIS bit that corresponds to the data-out pin of the SPI module connected to the device. | TRISGbits.TRISG8
xxxxxx_SPI_IF | Points to the interrupt flag for the SPI module connected to the device. | IFS2bits.SPI2IF
xxxxxx_SSPBUF | Points to the SPI buffer register for the SPI module connected to the device. | SPI2BUF
xxxxxx_SPICON1 | Points to the SPI control register for the SPI module connected to the device. | SPI2CON1
xxxxxx_SPICON1bits | Provides bitwise access to the SPI control register for the SPI module connected to the device. The ____bits registers are typically defined in the processor’s header files. | SPI2CON1bits
xxxxxx_SPICON2 | Points to the second SPI control register for the SPI module connected to the device. If your device doesn’t have an SPICON2 register (e.g. PIC32) just omit this definition. | SPI2CON2
xxxxxx_SPISTAT | Points to the SPI status register for the SPI module connected to the device. | SPI2STAT
xxxxxx_SPISTATbits | Provides bitwise access to the SPI status register for the SPI module connected to the device. | SPI2STATbits
xxxxxx_SPIBRG | Points to the SPI Baud Rate Generator register for the SPI module connected to the device. If your device doesn’t have a BRG-based SPI module, just omit this definition. | SPI2BRG
Configuring the Stack > Hardware Configuration > External Storage


ENC28J60 Config

Contents | Index | Home
Previous | Up | Next
ENC28J60 Config

To use the ENC28J60 in your project, include the files ‘ENC28J60.c” and “ENC28J60.h” in your project and uncomment the following macro in HardwareProfile.h:

#define ENC_CS_TRIS xxxxxxxxxxxxxxx

Several macros need to be mapped to registers or register bits when using the ENC28J60. They include:

Macro | Purpose | Sample Value
ENC_CS_IO | Defines the LAT (or PORT, where applicable) register bit that corresponds to the chip select pin. Defining this macro will also indicate that the stack should use the ENC28J60. | LATDbits.LATD14
ENC_CS_TRIS | Defines the TRIS bit that corresponds to the chip select pin. | TRISDbits.TRISD14
ENC_RST_IO | Defines the LAT (or PORT, where applicable) register bit that corresponds to the reset pin. If you leave the reset pin unconnected in your design, comment this macro out. | LATDbits.LATD15
ENC_RST_TRIS | Defines the TRIS bit that corresponds to the reset pin. | TRISDbits.TRISD15
ENC_SPI_IF | Points to the interrupt flag for the SPI module connected to the chip. | IFS0bits.SPI1IF
ENC_SSPBUF | Points to the SPI buffer register for the SPI module connected to the chip. | SPI1BUF
ENC_SPISTAT | Points to the SPI status register for the SPI module connected to the chip. | SPI1STAT
ENC_SPISTATbits | Provides bitwise access to the SPI status register for the SPI module connected to the chip. The ____bits registers are typically defined in the processor’s header files. | SPI1STATbits
ENC_SPICON1 | Points to the SPI control register for the SPI module connected to the chip. | SPI1CON1
ENC_SPICON1bits | Provides bitwise access to the SPI control register for the SPI module connected to the chip (see ENC_SPISTATbits entry). | SPI1CON1bits
ENC_SPICON2 | Points to the second SPI control register for the SPI module connected to the chip. If your device doesn’t have an SPICON2 register (e.g. PIC32) just omit this definition. | SPI1CON2
ENC_SPIBRG | Points to the SPI Baud Rate Generator register for the SPI module connected to the chip. If your device doesn’t have a BRG-based SPI module, just omit this definition. | SPI1BRG
Configuring the Stack > Hardware Configuration > ENC28J60 Config


ENCX24J600 Config

Contents | Index | Home
Previous | Up | Next
ENCX24J600 Config

To use the ENC624J600 or -424J600 in your project, include “ENCX24J600.c” and “ENCX24J600.h” and uncomment the following macro in HardwareProfile.h:

Copy Code
#define ENC100_INTERFACE_MODE 0

The parameter ‘0’ indicates that you’ll be using the device in SPI mode. Potential usable parameters include:

Parameter | Functionality
0 | SPI mode using CS, SCK, SI, and SO pins
1 | 8-bit demultiplexed PSP Mode 1 with RD and WR pins
2 | 8-bit demultiplexed PSP Mode 2 with R/~W and EN pins
3 | 16-bit demultiplexed PSP Mode 3 with Rd, WRL, and WRH pins
4 | 16-bit demultiplexed PSP Mode 4 with R/~W, B0SEL, and B1SEL pins
5 | 8-bit multiplexed PSP Mode 5 with RD and WR pins
6 | 8-bit multiplexed PSP Mode 6 with R/~W and EN pins
9 | 16-bit multiplexed PSP Mode 9 with AL, RD, WRL, and WRH pins
10 | 16-bit multiplexed PSP Mode 10 with AL, R/~W, B0SEL, and B1SEL pins

More information on the functionality of each mode is available in the ENC624J600 family datasheet. Note, however, that the 44-pin ENC424J600 only supports communication using the SPI mode and PSP Modes 5 and 6. Also, because of board conflicts, PSP Modes 2, 4, 6, and 10 shouldn’t be used with the Explorer 16 (and PSP Mode 3 may cause bus contention with the 25LC256 EEPROM).

Several macros need to be mapped to registers or register bits when using the ENCX24J600 as well. In addition, some features can be enabled/disabled for this device by defining certain macros. Macros include:

Macro | Purpose | Sample Value
ENC100_INTERFACE_MODE | Indicates which communication mode the stack should use to interface to the chip. This macro will also indicate that the stack should use the ENCX24J600. | 0
ENC100_PSP_USE_INDIRECT_- RAM_ADDRESSING | Un-commenting this macro will allow the stack to indirectly address the RAM of the ENCX24J600 (to save some address wires). For SPI mode or PSP Modes 9 and 10, this option will be ignored. | N/A
ENC100_TRANSLATE_TO_PIN- _ADDR(a) | This macro will actually remap the addresses passed into the parallel interface to fit the configuration of the pins (if you are using indirect addressing). | ((((a)&0x100)<<6) | ((a&0x00FF))
ENC100_MDIX_IO | If you design an Auto-crossover (Auto-MDIX) circuit into your board, this macro will define the pin to use for it. See the Fast 100Mbps Ethernet PICtail/PICtail Plus board schematic for an example circuit. | LATBbits.LATB3
ENC100_MDIX_TRIS | Defines the TRIS bit to use for the Auto-crossover circuit. | TRISBbits.TRISB3
ENC100_INT_IO | Defines an I/O pin to use for the chip’s interrupt signal pin. This feature is currently unused by the stack. | PORTAbits.RA13
ENC100_INT_TRIS | Defines a TRIS bit to use for the chip’s interrupt signal pin. | TRISAbits.TRISA13
ENC100_CS_IO | Defines a port bit for use with the chip select pin. Optional in PSP modes. | LATAbits.LATA5
ENC100_CS_TRIS | Defines a TRIS bit to use for the chip select pin. | TRISAbits.TRISA5
ENC100_POR_IO | Defines the port bit to use with a power disconnect circuit. If your application doesn’t have this feature implemented, comment out this bit. | LATCbits.LATC1
ENC100_POR_TRIS | Defines the TRIS bit to use with a power disconnect circuit. | TRISCbits.TRISC1
ENC100_SO_WR_B0SEL_EN_IO | Defines a pin used for communication. The functionality of this pin depends on which communication mode in selected. It can be equivalent to the ENCX24J600 serial out pin, the parallel mode WR strobe, the B0SEL pin, or the EN pin. | LATDbits.LATD4
ENC100_SO_WR_B0SEL_EN_TRIS | Defines the TRIS bit to use with the ENC100_SO_WR_B0SEL_EN_IO pin. | TRISDbits.TRISD4
ENC100_SI_RD_RW_IO | Defines a pin used for communication. The functionality of this pin depends on which communication mode in selected. It can be equivalent to the ENCX24J600 serial in pin, the parallel mode RD strobe, or the R/~W pin. | LATDbits.LATD5
ENC100_SI_RD_RW_TRIS | Defines the TRIS bit to use with the ENC100_SI_RD_RW_IO pin. | TRISDbits.TRISD5
ENC100_SCK_AL_IO | Defines a pin used for communication. The functionality of this pin depends on which communication mode in selected. It can be equivalent to the ENCX24J600 serial clock pin or the parallel mode address latch strobe. | LATDbits.LATDB15
ENC100_SCK_AL_TRIS | Defines the TRIS bit to use with the ENC100_SCK_AL_IO pin. | TRISDbits.TRISD15
ENC100_ISR_ENABLE | Points to the bit to enable the interrupt for the I/O based ENCX24J600-triggered interrupt. This feature is not currently implemented. | IEC1bits.INT2IE
ENC100_ISR_FLAG | Points to the interrupt flag bit for the I/O based ENCX24J600-triggered interrupt. This feature is not currently implemented. | IFS1bits.INT2IF
ENC100_ISR_POLARITY | Points to the interrupt polarity bit for the I/O based ENCX24J600-triggered interrupt. This feature is not currently implemented. | INTCON2bits.INT2EP
ENC100_ISR_PRIORITY | Points to the interrupt priority bit for the I/O based ENCX24J600-triggered interrupt. This feature is not currently implemented. | IPC7bits.INT2IP
ENC100_SPI_ENABLE | Points to the SPI module enable bit if SPI mode is used. | SPI1STATbits.SPIEN
ENC100_SPI_IF | Points to the interrupt flag for the SPI module if SPI mode is used. | IFS0bits.SPI1IF
ENC100_SSPBUF | Points to the SPI buffer register for the SPI module if SPI mode is used. | SPI1BUF
ENC100_SPISTAT | Points to the SPI status register for the SPI module if SPI mode is used. | SPI1STAT
ENC100_SPISTATbits | Provides bitwise access to the SPI status register for the SPI if SPI mode is used. The ____bits registers are typically defined in the processor’s header files. | SPI1STATbits
ENC100_SPICON1 | Points to the SPI control register for the SPI module if SPI mode is used. | SPI1CON1
ENC100_SPICON1bits | Provides bitwise access to the SPI control register for the SPI module if SPI mode is used (see ENC_SPISTATbits entry). | SPI1CON1bits
ENC100_SPICON2 | Points to the second SPI control register for the SPI module if SPI mode is used. If your device doesn’t have an SPICON2 register (e.g. PIC32) just omit this definition. | SPI1CON2
ENC100_SPIBRG | Points to the SPI Baud Rate Generator register for the SPI module if SPI mode is used. If your device doesn’t have a BRG-based SPI module, just omit this definition. | SPI1BRG
Configuring the Stack > Hardware Configuration > ENCX24J600 Config


PIC18F97J60 Config

Contents | Index | Home
Previous | Up | Next
PIC18F97J60 Config

The 18F97J60 can be used in your application by selecting it as the processor in MPLAB, ensuring that the ENC_CS_TRIS macro is commented out, and including the files “ETH97J60.c” and “ETH97J60.h.” There are no additional macros to define for the 97J60; since it uses its own internal MAC and PHY for communication all of the register names and bit names are fixed.

Configuring the Stack > Hardware Configuration > PIC18F97J60 Config


PIC32MX7XX Config

Contents | Index | Home
Previous | Up | Next
PIC32MX7XX Config

To use the PIC32MX795 in your project, include the files ETHPIC32IntMac.c and ETHPIC32ExtPhy.c in your project. You’ll also have to add a specific PHY implementation file (by default ETHPIC32ExtPhyDP83848.c is provided) depending on your actual external PHY selection.

Update the following definitions in HardwareProfile.h:

Macro | Purpose | Sample Value
PHY_RMII | Define this macro if the external PHY runs in RMII mode. Comment it out if you’re using an MII PHY. | -
PHY_CONFIG_ALTERNATE | Define this symbol if the PIC32MX7XX uses the alternate configuration pins to connect to the PHY. Comment it out for the default configuration pins. | -
PHY_ADDRESS | Update with the MIIM address of the external PHY you are using (the address on which the PHY responds to MIIM transactions. See the PHY datasheet). | 0x1

Update the following definitions in TCPIPConfig.h:

Macro | Purpose | Sample Value
ETH_CFG_LINK | Set to 0 to use the default connection characteristics (depends on the selected PHY). Set to 1 to configure the Ethernet link to the following specific parameters. Auto-negotiation will always be enabled if supported by the PHY. | 0
ETH_CFG_AUTO | Set to 1 to use auto negotiation. Strongly recommended. | 1
ETH_CFG_10 | Use/advertise 10 Mbps capability. | 1
ETH_CFG_100 | Use/advertise 100 Mbps capability. | 1
ETH_CFG_HDUPLEX | Use/advertise half duplex capability. | 1
ETH_CFG_FDUPLEX | Use/advertise full duplex capability. | 1
ETH_CFG_AUTO_MDIX | Use/advertise auto MDIX capability (effective only when ETH_CFG_AUTO is enabled). | 1
ETH_CFG_SWAP_MDIX | Use swapped MDIX if defined. Otherwise, use normal MDIX. | 1
Configuring the Stack > Hardware Configuration > PIC32MX7XX Config


Address

Contents | Index | Home
Previous | Up | Next
Address

A TCP/IP application will need to have both a Media Access Control (MAC) address and an Internet Protocol (IP) address. There are multiple methods for obtaining or setting these addresses.

Topics
Name | Description
MAC Address | Describes how to configure the MAC address on your device.
IP Address | Describes how to configure your application's IP address.
Configuring the Stack > Address


MAC Address

Contents | Index | Home
Previous | Up | Next
MAC Address

The 6-byte MAC address provides addressing for the Media Access Control protocol layer of the TCP/IP stack. MAC addresses are permanent addresses tied to hardware. Blocks of MAC addresses are sold to organizations and individuals by the IEEE; if you aren't using a Microchip device with a built-in MAC address, you will need to purchase one of these blocks to assign MAC addresses to your products.

The MAC address is defined in the firmware configuration header "TCPIPConfig.h." There are six macros that must be defined in this file to set the MAC address. They are:

Macro | Sample Value
MY_DEFAULT_MAC_BYTE1 | (0x00)
MY_DEFAULT_MAC_BYTE2 | (0x04)
MY_DEFAULT_MAC_BYTE3 | (0xA3)
MY_DEFAULT_MAC_BYTE4 | (0x00)
MY_DEFAULT_MAC_BYTE5 | (0x00)
MY_DEFAULT_MAC_BYTE6 | (0x00)

Each of these macros represents a byte of the MAC address (note that 00:04:A3:xx:xx:xx is the block of MAC addresses reserved for Microchip products). Once you obtain your block of addresses, you will need to specify a unique address for every device you produce. The "TCP/IP Demo App" demonstration project describes a method for using Microchip's MPLAB PM3 programmer to serially program a range of MAC addresses into multiple parts without recompiling your project.

The ENCX24J600, MRF24WB0M, and PIC32MX7XX/6XX feature a pre-programmed MAC address (from Microchip's address block). If you are using either of these part families in your project, you can define your MAC address as "00:04:A3:00:00:00" and the stack will automatically use the part's pre-programmed address for your application.

Microchip also provides a [image] family of EEPROMs that include a unique, pre-programmed EUI-48 (MAC) or EUI-64 address. When using one of these devices, you can write your AppConfig initialization code so it will obtain the device's MAC address from one of these EEPROMs instead of the default MAC address macros.

Configuring the Stack > Address > MAC Address


IP Address

Contents | Index | Home
Previous | Up | Next
IP Address

The IP address is used to address nodes on an Internet Protocol network. You will need to configure your application with an IP address, or enable a method to obtain one. You may also want to define a few other parameters that describe how your device will try to fit into its network, by default.

The macros that you will need to define include:

Macro | Property | Sample Value
MY_DEFAULT_IP_ADDR_BYTE1 | Default IP address byte 1 | 192ul
MY_DEFAULT_IP_ADDR_BYTE2 | Default IP address byte 2 | 168ul
MY_DEFAULT_IP_ADDR_BYTE3 | Default IP address byte 3 | 1ul
MY_DEFAULT_IP_ADDR_BYTE4 | Default IP address byte 4 | 100ul
MY_DEFAULT_MASK_BYTE1 | Default subnet mask byte 1 | 255ul
MY_DEFAULT_MASK_BYTE2 | Default subnet mask byte 2 | 255ul
MY_DEFAULT_MASK_BYTE3 | Default subnet mask byte 3 | 255ul
MY_DEFAULT_MASK_BYTE4 | Default subnet mask byte 4 | 0ul
MY_DEFAULT_GATE_BYTE1 | Default gateway byte 1 | 192ul
MY_DEFAULT_GATE_BYTE1 | Default gateway byte 2 | 168ul
MY_DEFAULT_GATE_BYTE1 | Default gateway byte 3 | 1ul
MY_DEFAULT_GATE_BYTE1 | Default gateway byte 4 | 1ul

The subnet address is a bit mask that defines the scope of the network. If your IP address is 192.168.5.100, and you specify a subnet mask of 255.255.255.0, the stack will assume that addresses in the range 192.168.5.x are on the same subnet that you are, and that packets sent to any of those addresses won't have to be routed anywhere else.

The default gateway is the IP address of the node on the network that your application will send packets to if it doesn't know how to route them to the address it wants to send them to. If your application is on the 192.268.5.x subnet, if it wants to send a packet to 198.175.253.160 and it doesn't know exactly how to get there, it will send it to the default gateway.

Note that if you write your own code instead of starting with a demo application, you will need to populate your AppConfig structure with these values. Also note that these are only default values. Other protocols (or your application itself) may modify any of the APP_CONFIG fields that represent these parameters.

There are three methods that you can use to set or obtain an IP address: static, DHCP, or AutoIP.

Static IP Addressing

Using a static address will allow you to specify a set IP address. This can either be done at compile time, by setting the default IP address to the value you'd like to use and using the demo code (which populated your AppConfig structure automatically), or during run-time, by programming your application to set the IP address in your AppConfig structure based on some input. If you'd like to include the code for DCHP and AutoIP address acquisition if your project but still use static addressing, you can call the DHCP and AutoIP functions that disable those modules to prevent them from overwriting your IP address. Use of static addresses will usually only work if the server is configured to support that address.

DHCP

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. To use DHCP, include the files DHCP.c, DHCPs.c, and DHCP.h in your project, and add or uncomment the definition "#define STACK_USE_DHCP_CLIENT" to TCPIPConfig.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 STACK_USE_DHCP_SERVER" to TCPIPConfig.h.

AutoIP

The AutoIP module will allow your application to choose an IP address and claim it for itself. These addresses are link-local, meaning they cannot be routed, and will only work on your local link. This functionality is based on the specification for allocating dynamic link-local addresses, but is modified to take the form used by Microsoft's APIPA link-local address allocation scheme. To enable this feature, include the files AutoIP.c and AutoIP.h and add the macro "#define STACK_USE_AUTO_IP" to TCPIPConfig.h.

IP Address Module Interaction

It is possible to configure a default static address and enable DHCP and AutoIP at the same time. If you don't disable one or the other, the AutoIP module will immediately choose an address in the specified address range and begin attempting to claim it. DHCP will also begin sending messages to attempt to lease a DHCP IP address from a DHCP server. In most cases the DHCP module will complete all of its transactions before AutoIP finishes claiming its address. In this case, the DHCP address will be copied to the AppConfig structure and the AutoIP module will stop trying to claim its address. Since a routable DHCP address is always preferred to a link-local AutoIP address, the stack will also immediately start using a DHCP address if it becomes available, even if an AutoIP address was already in use (i.e. if you enable DHCP after AutoIP has already claimed an address). This may cause existing open sockets to lose communication; they should be re-opened with the new address. In this situation, you can also use a static address if you disable DHCP and AutoIP and set the static address in the AppConfig structure.

If AutoIP is used in conjunction with the DHCP Server module, the AutoIP module will generate an address in the 169.254.x.x subnet and then serve another address in the same subnet to the DHCP client connected to the board.

Configuring the Stack > Address > IP Address


Protocol Configuration

Contents | Index | Home
Previous | Up | Next
Protocol Configuration

There are a few steps that you must take to include each protocol in your application. Most of this configuration is performed by setting options in one of the variants of the TCPIPConfig.h header file. Nearly all protocols will require you to enable them by defining one or more macros in TCPIPConfig.h. You will also need to include the files needed by your protocols in your project. Some protocols will require you to define sockets for them to use in TCPIPConfig.h, and allocate memory to them.

The TCP/IP Configuration Wizard, included with the stack, will allow you to select the features that you want while handling most complex firmware configuration automatically. Because of this, it is the easiest (and safest) way to set up your application protocols.

The Module APIs topic has a description of each of the modules.

Topics
Name | Description
Protocol Macros and Files | Describes macros and files that must be included to use protocols.
Additional Features | Describes additional firmware demos and functionality.
Sockets | Describes how to set up sockets for your application.
Configuring the Stack > Protocol Configuration


Protocol Macros and Files

Contents | Index | Home
Previous | Up | Next
Protocol Macros and Files

You will need to define some macros in TCPIPConfig.h and include some files in your project to enable each protocol. These include:

Module | Macro | Function | Required Files
ICMP | STACK_USE_ICMP_SERVER | Provides the ability to query and respond to pings. | ICMP.c, ICMP.h
ICMP | STACK_USE_ICMP_CLIENT | Provides the ability to transmit pings. | ICMP.c, ICMP.h
HTTP2 | STACK_USE_HTTP2_SERVER | Provides HTTP server functionality with dynamic variables, POST, Cookies, Authentication, and other features | HTTP2.c, HTTP2.h, TCP.c, TCP.h, CustomHTTPApp.c and HTTPPrint.h (see HTTP2 section for information on these files)
SSL | STACK_USE_SSL_SERVER | Provides support for SSL server sockets. | SSL.c, SSL.h, ARCFOUR.c, ARCFOUR.h, BigInt.c, BigInt.h, Random.c, Random.h, RSA.c, RSA.h
SSL | STACK_USE_SSL_CLIENT | Provides support for SSL client sockets. | SSL.c, SSL.h, ARCFOUR.c, ARCFOUR.h, BigInt.c, BigInt.h, Random.c, Random.h, RSA.c, RSA.h
FTP | STACK_USE_FTP_SERVER | Provides ability to remotely upload MPFS2 images to HTTP2 servers via FTP | FTP.c, FTP.h, TCP.c, TCP.h
SMTP | STACK_USE_SMTP_CLIENT | Provides the ability to send email | SMTP.c, SMTP.h, TCP.c, TCP.h, Helpers.c, Helpers.h
SNMP | STACK_USE_SNMP_SERVER | Provides a network-based machine control/monitoring protocol | SNMP.c, SNMP.h, UDP.c, UDP.h
TFTP | STACK_USE_TFTP_CLIENT | Provides unreliable file upload/download services | TFTPc.c, TFTPc.h, TCP.c, TCP.h
Telnet | STACK_USE_TELNET_SERVER | Provides telnet services. | Telnet.c, Telnet.h, TCP.c, TCP.h
Announce | STACK_USE_ANNOUNCE | Provides device hostname and IP address discovery on a local Ethernet subnet | Announce.c, Announce.h
DNS | STACK_USE_DNS | Provides the ability to resolve hostnames to IP addresses | DNS.c, DNS.h, UDP.c, UDP.h
NBNS | STACK_USE_NBNS | Provides the ability to resolve hostnames to IP addresses on the same subnet. | NBNS.c, NBNS.h, UDP.c, UDP.h
SNTP | STACK_USE_SNTP_CLIENT | Provides the ability to get the date/time from the internet | SNTP.c, SNTP.h, UDP.c, UDP.h
Dynamic DNS | STACK_USE_DYNAMICDNS_CLIENT | Provides the ability to resolve hostnames to IP addresses that change frequently. | DynDNS.c, DynDNS.h, TCP.c, TCP.h
MPFS2 | STACK_USE_MPFS2 | Provides MPFS2 services for custom applications. This functionality will be enabled/required automatically by stack-based protocols that require MPFS2. | MPFS2.c, MPFS2.h
TCP | STACK_USE_TCP | Provides TCP transport layer services for custom protocols. This functionality is automatically enabled/required by stack-based protocols that require TCP sockets. | TCP.c, TCP.h
UDP | STACK_USE_UDP | Provides UDP transport layer services for custom protocols. This functionality is automatically enabled/required by stack-based protocols that require UDP sockets. | UDP.c, UDP.h
Configuring the Stack > Protocol Configuration > Protocol Macros and Files


Additional Features

Contents | Index | Home
Previous | Up | Next
Additional Features

The TCP/IP stack includes some additional functionality that can be enabled in TCPIPConfig.h.

Feature | Macro | Description | Required Files
UART Demo | STACK_USE_UART | Application demo using UART for IP address display and stack configuration. | UART.c, UART.h
UART-to-TCP Bridge | STACK_USE_UART2TCP_BRIDGE | UART to TCP Bridge application example | UART2TCPBridge.c, UART2TCPBridge.h
IP Gleaning | STACK_USE_IP_GLEANING | Allows assignment of an IP address via reception of an ICMP packet with a valid IP during configuration mode | -
Reboot Server | STACK_USE_REBOOT_SERVER | Allows the PIC to be reset remotely (useful for bootloaders). | Reboot.c, Reboot.h
UDP Performance Test | STACK_USE_UDP_PERFORMANCE_TEST | UDP performance test. Monitor a local area network for UDP packets with a packet sniffer. This test will transmit 1024 packets. Use the timestamps of the first and last packets to calculate throughput. | UDPPerformanceTest.c, UDPPerformanceTest.h
TCP Performance Test | STACK_USE_TCP_PERFORMACE_TEST | TCP performance test. Connect a demo board to a PC via UART, execute the code, and monitor the throughput on the PC terminal. | TCPPerformanceTest.c, TCPPerformanceTest.h
Berkeley API | STACK_USE_BERKELEY_API | Provides a Berkeley Sockets API abstraction layer. | BerkeleyAPI.c, BerkeleyAPI.h
Configuring the Stack > Protocol Configuration > Additional Features


Sockets

Contents | Index | Home
Previous | Up | Next
Sockets

Most of your application protocols will require you to allocate memory for each connection (socket) that you have open. Like the other firmware configuration options, this is controlled by the definition of macros in TCPIPConfig.h. For TCP sockets, you will have to specify four initialization parameters for each socket, including the purpose of that socket, the type of memory the socket should be stored in, the size of the transmit FIFO, and the size of the receive FIFO. The stack will then initialize the sockets with this information, and create a TCP Control Block (TCB) for each to control its operations. This topic will outline the socket configuration functionality in the sample version of TCPIPConfig.h that is included with the TCP/IP Demo App project.

Topics
Name | Description
Memory Allocation | Describes memory allocation macros.
Socket Types | Describes socket types.
Initialization Structure | Describes the structure used to declare and initialize TCP sockets.
UDP Sockets | Describes how UDP sockets are defined.
BSD Sockets | Describes the allocation of BSD sockets.
Configuring the Stack > Protocol Configuration > Sockets


Memory Allocation

Contents | Index | Home
Previous | Up | Next
Memory Allocation
#define TCP_ETH_RAM_SIZE (3900ul)
#define TCP_PIC_RAM_SIZE (0ul)
#define TCP_SPI_RAM_SIZE (0ul)
#define TCP_SPI_RAM_BASE_ADDRESS (0ul)

The first four macros in the socket section are used to describe the total amount of memory used to contain sockets. When data is sent from a TCP socket, it will first be copied into the socket's transmit FIFO, and then to the MAC/PHY transmit buffer. Similarly, received data will be read from the MAC/PHY chip into the receive FIFO. These FIFOs, as well as the TCB, can be stored in 3 places.

TCP_ETH_RAM_SIZE is used to define the RAM available for sockets on the actual TCP/IP MAC/PHY chip. This will not be the same as the total RAM on the chip; some memory must be reserved for packets being transmitted and received. By default ~1518 bytes (the maximum single-packet transmission size) will be reserved for TX packets on Microchip parts. The amount reserved for the receive packet buffer will equal the amount remaining after allocating the memory for the TX buffer and the memory for the sockets. You may receive a compile-time warning if the RX buffer is unreasonably small.

TCP_PIC_RAM_SIZE is used to define the RAM available for sockets on the PIC microcontroller that's driving your application.

TCP_SPI_RAM_SIZE defines the RAM available for sockets on an external SPI RAM (see External Storage). You can specify the base address in this RAM chip to use with the TCP_SPI_RAM_BASE_ADDRESS macro.

Configuring the Stack > Protocol Configuration > Sockets > Memory Allocation


Socket Types

Contents | Index | Home
Previous | Up | Next
Socket Types

When creating an initialization list for your sockets, you will have to specify a socket type. This parameter will define which protocol can use the socket. You can create and delete socket types as you require. In the sample version of TCPIPConfig.h, the following types are defined:

#define TCP_SOCKET_TYPES
    #define TCP_PURPOSE_GENERIC_TCP_CLIENT 0
    #define TCP_PURPOSE_GENERIC_TCP_SERVER 1
    #define TCP_PURPOSE_TELNET 2
    #define TCP_PURPOSE_FTP_COMMAND 3
    #define TCP_PURPOSE_FTP_DATA 4
    #define TCP_PURPOSE_TCP_PERFORMANCE_TX 5
    #define TCP_PURPOSE_TCP_PERFORMANCE_RX 6
    #define TCP_PURPOSE_UART_2_TCP_BRIDGE 7
    #define TCP_PURPOSE_HTTP_SERVER 8
    #define TCP_PURPOSE_DEFAULT 9
    #define TCP_PURPOSE_BERKELEY_SERVER 10
    #define TCP_PURPOSE_BERKELEY_CLIENT 11
#define END_OF_TCP_SOCKET_TYPES

The TCP_PURPOSE_GENERIC_TCP_CLIENT and TCP_PURPOSE_GENERIC_TCP_SERVER socket types are used by the generic TCP client and server examples (see GenericTCPClient.c and GenericTCPServer.c). These files are used as an example of how to create a new, custom TCP client or server application.

If you are trying to open a Telnet connection, the stack will try to use a TCP_PURPOSE_TELNET socket.

The TCP_PURPOSE_FTP_COMMAND and TCP_PURPOSE_FTP_DATA socket types are used to receive FTP commands and data.

The two TCP_PERFORMANCE_x socket types are used solely to conduct TCP performance testing.

The TCP_PURPOSE_UART_2_TCP_BRIDGE socket type is used for the UART-to-TCP bridge example.

The TCP_PURPOSE_HTTP_SERVER socket type is used for sockets on HTTP servers that listen for web page view requests.

The TCP_PURPOSE_DEFAULT socket type can be used for miscellaneous applications, or for applications that only need sockets temporairly. Dynamic DNS connections and SMTP connections use default sockets, and the legacy wrapper implementation for the TCPListen and TCPConnect functions try to open them.

The TCP_PURPOSE_BERKELEY_SERVER and TCP_PURPOSE_BERKELEY_CLIENT socket types indicate that a socket is available for the use of the Berkeley API layer (also see BSD Sockets).

Configuring the Stack > Protocol Configuration > Sockets > Socket Types


Initialization Structure

Contents | Index | Home
Previous | Up | Next
Initialization Structure

In the TCPIPConfig.h header file, you must also define an array of structures to declare and initialize any sockets that you need. The sample structure is:

#define TCP_CONFIGURATION ROM struct {
BYTE vSocketPurpose, BYTE vMemoryMedium, WORD wTXBufferSize, WORD wRXBufferSize }
TCPSocketInitializer[] =
{
    {TCP_PURPOSE_GENERIC_TCP_CLIENT, TCP_ETH_RAM, 125, 100},
    {TCP_PURPOSE_GENERIC_TCP_SERVER, TCP_ETH_RAM, 20, 20},
    {TCP_PURPOSE_TELNET, TCP_ETH_RAM, 200, 150},
    //{TCP_PURPOSE_TELNET, TCP_ETH_RAM, 200, 150},
    //{TCP_PURPOSE_TELNET, TCP_ETH_RAM, 200, 150},
    //{TCP_PURPOSE_FTP_COMMAND, TCP_ETH_RAM, 100, 40},
    //{TCP_PURPOSE_FTP_DATA, TCP_ETH_RAM, 0, 128},
    {TCP_PURPOSE_TCP_PERFORMANCE_TX, TCP_ETH_RAM, 200, 1},
    //{TCP_PURPOSE_TCP_PERFORMANCE_RX, TCP_ETH_RAM, 40, 1500},
    {TCP_PURPOSE_UART_2_TCP_BRIDGE, TCP_ETH_RAM, 256, 256},
    {TCP_PURPOSE_HTTP_SERVER, TCP_ETH_RAM, 200, 200},
    {TCP_PURPOSE_HTTP_SERVER, TCP_ETH_RAM, 200, 200},
    {TCP_PURPOSE_DEFAULT, TCP_ETH_RAM, 200, 200},
    {TCP_PURPOSE_BERKELEY_SERVER, TCP_ETH_RAM, 25, 20},
    //{TCP_PURPOSE_BERKELEY_SERVER, TCP_ETH_RAM, 25, 20},
    //{TCP_PURPOSE_BERKELEY_SERVER, TCP_ETH_RAM, 25, 20},
    //{TCP_PURPOSE_BERKELEY_CLIENT, TCP_ETH_RAM, 125, 100},
};
#define END_OF_TCP_CONFIGURATION

As you can see from the structure parameters, the four parameters you'll need to include in each of your socket declarations are:

  • Socket purpose/type
  • RAM storage location
  • TX FIFO buffer size
  • RX FIFO buffer size

Several example socket declarations are listed. The socket purpose for each corresponds to one of the socket types. The RAM storage for each socket example sets the location to TCP_ETH_RAM (the MAC/PHY chip RAM). Other options are TCP_PIC_RAM (the PIC's own RAM) and TCP_SPI_RAM (an external SPI RAM device). Finally, the TX and RX FIFOs are declared. Each RX buffer must contain at least one byte, to handle the SYN and FIN messages required by TCP. Each socket you declare will require up to 48 bytes of PIC RAM, and 40 + (TX FIFO size) + (RX FIFO size) bytes of RAM on the storage medium that you select.

Configuring the Stack > Protocol Configuration > Sockets > Initialization Structure


UDP Sockets

Contents | Index | Home
Previous | Up | Next
UDP Sockets

UDP sockets are somewhat easier to declare than TCP sockets. Since UDP transmissions don't have to be processed in a particular order and responses aren't required by the sender, you don't have to declare separate buffers for these sockets. There are two options to define when using UDP:

#define MAX_UDP_SOCKETS     (10u)
//#define UDP_USE_TX_CHECKSUM

The MAX_UDP_SOCKETS definition defines the size of an array of UDP_SOCKET_INFO structures. These structures contain two sixteen-bit identifiers for the remote node's and local node's UDP port numbers, and a 10-byte structure used to hold the remote node's MAC address and IP address (these structures use the packed attribute, so the actual size of the UDP_SOCKET_INFO structure may very slightly depending on the PIC architecture you use).

The UDP_USE_TX_CHECKSUM definition will cause the stack to generate checksums for transmitted data, and include them with transmitted packets. This can provide some data integrity verification, but it will also decrease TX performance by nearly 50% unless the ENCX24J600 is used (the ENCX24J600 chips include hardware checksum calculators).

Configuring the Stack > Protocol Configuration > Sockets > UDP Sockets


BSD Sockets

Contents | Index | Home
Previous | Up | Next
BSD Sockets

The Berkeley API socket configuration option will require Berkeley sockets. Each one of these internally uses one TCP or UDP socket, defined by the TCPSocketInitializer[] array and the MAX_UDP_SOCKETS definition. Because of this, the number of Berkeley sockets you declare must be less than or equal to the sum of the number of UDP sockets you declare and the number of TCP Berkeley-type sockets you declare. The TCPIPConfig.h macro to define the number of Berkeley sockets is:

#define BSD_SOCKET_COUNT    (5u)
Configuring the Stack > Protocol Configuration > Sockets > BSD Sockets


Stack API

Contents | Index | Home
Previous | Next
Stack API

The Microchip TCP/IP Stack is implemented as a suite of modules. Each module exists on its own layer in the TCP/IP layer model, and has its own set of APIs. These APIs are described in this section

Modules
Name | Description
Announce | Provides a UDP MAC address announcement feature.
ARP | Provides Address Resolution Protocol support.
Berkeley (BSD) Sockets | Provides a BSD socket wrapper to the Microchip TCP/IP Stack.
DNS Client | Provides Domain Name Service resolution.
Dynamic DNS Client | Updates an external IP address to a Dynamic DNS service.
Hashes | Calculates MD5 and SHA-1 hash sums.
Helpers | Provides several helper function for stack operation.
HTTP2 Server | Provides an advanced embedded web server.
ICMP | Provides Ping functionality.
MPFS2 | Provides a light-weight file system.
NBNS | Describes the NetBIOS Name Service protocol.
Performance Tests | Tests TCP and UDP performance of an application.
SMTP Client | Sends e-mail messages across the internet.
Reboot | Provides a service to remotely reboot the PIC.
SNMP | Provides an Simple Network Management Protocol agent.
SNTP Client | Obtains absolute time stamps from a pool of network time servers.
SSL | Implements SSL encryption for TCP connections.
TCP | Implements the TCP transport layer protocol.
Telnet | Describes the operation of the Telnet module.
TFTP | Describes the TFTP module.
Tick Module | Provides accurate time-keeping capabilities.
UDP | Implements the UDP transport layer protocol.
Stack API


Announce

Contents | Index | Home
Previous | Up | Next
Announce

This module will facilitate device discovery on DHCP enabled networks by broadcasting a UDP message on port 30303 whenever the local IP address changes. You can change the port used by the announce module by changing the following macro definition in Announce.c.

#define ANNOUNCE_PORT   30303

The Announce protocol is designed to be used with the TCP/IP Discoverer PC program.

Topics
Name | Description
Announce Stack Members | Functions and variables intended to be accessed only by the stack.
Stack API > Announce


Announce Stack Members

Contents | Index | Home
Previous | Up | Next
Announce Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
AnnounceIP | Transmits an Announce packet.
DiscoveryTask | Announce callback task.
Module

Announce

Stack API > Announce > Stack Members


AnnounceIP Function

Contents | Index | Home
Previous | Up | Next
AnnounceIP Function
C
void AnnounceIP();
Description

AnnounceIP opens a UDP socket and transmits a broadcast packet to port 30303. If a computer is on the same subnet and a utility is looking for packets on the UDP port, it will receive the broadcast. For this application, it is used to announce the change of this board's IP address. The messages can be viewed with the TCP/IP Discoverer software tool.

Preconditions

Stack is initialized()

Returns

None

Side Effects

None

Remarks

A UDP socket must be available before this function is called. It is freed at the end of the function. MAX_UDP_SOCKETS may need to be increased if other modules use UDP sockets.

Stack API > Announce > Stack Members > AnnounceIP Function


DiscoveryTask Function

Contents | Index | Home
Previous | Up | Next
DiscoveryTask Function
C
void DiscoveryTask();
Description

Recurring task used to listen for Discovery messages on the specified ANNOUNCE_PORT. These messages can be sent using the Microchip Device Discoverer tool. If one is received, this function will transmit a reply.

Preconditions

Stack is initialized()

Returns

None

Side Effects

None

Remarks

A UDP socket must be available before this function is called. It is freed at the end of the function. MAX_UDP_SOCKETS may need to be increased if other modules use UDP sockets.

Stack API > Announce > Stack Members > DiscoveryTask Function


ARP

Contents | Index | Home
Previous | Up | Next
ARP
Types

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.

Responses to incoming ARP requests are processed automatically. Resolution of ARP requests follows a simple state machine, as indicated in the following diagram.

Topics
Name | Description
ARP Public Members | Functions and variables accessible by the stack application
ARP Stack Members | Functions and variables intended to be accessed only by the stack
ARP Internal Members | Functions and variables internal to the ARP module
Types | The following table lists types in this documentation.
Types
Name | Description
ARP_PACKET | ARP packet structure
Stack API > ARP


ARP Public Members

Contents | Index | Home
Previous | Up | Next
ARP Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
ARPResolve | Transmits an ARP request to resolve an IP address.
ARPIsResolved | Determines if an ARP request has been resolved yet.
ARPDeRegisterCallbacks | De-Registering callbacks with ARP module that are registered previously.
ARPRegisterCallbacks | Registering callback with ARP module to get notified about certian events.
ARPSendPkt | Transmits an ARP request/Reply initated by Application or external module.
Macros
Name | Description
ARP_REQ | Operation code indicating an ARP Request
ARP_RESP | Operation code indicating an ARP Response
MAX_REG_APPS | MAX num allowed registrations of Modules/Apps
Module

ARP

Structures
Name | Description
arp_app_callbacks | This is record arp_app_callbacks.
Stack API > ARP > Public Members


ARPResolve Function

Contents | Index | Home
Previous | Up | Next
ARPResolve Function
C
void ARPResolve(
    IP_ADDR* IPAddr
);
Description

This function transmits and ARP request to determine the hardware address of a given IP address.

Preconditions

None

Parameters
Parameters | Description
IPAddr | The IP address to be resolved. The address must be specified in network byte order (big endian).
Returns

None

Remarks

This function is only required when the stack is a client, and therefore is only enabled when STACK_CLIENT_MODE is enabled.

To retrieve the ARP query result, call the ARPIsResolved() function.

Stack API > ARP > Public Members > ARPResolve Function


ARPIsResolved Function

Contents | Index | Home
Previous | Up | Next
ARPIsResolved Function
C
BOOL ARPIsResolved(
    IP_ADDR* IPAddr,
    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 packet is ready in the MAC buffer.

Parameters
Parameters | Description
IPAddr | The IP address to be resolved. This must match the IP address provided to the ARPResolve() 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 ARPIsResolved() again at a later time. If you don't get a response after a application specific timeout period, you may want to call ARPResolve() 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.
Remarks

This function is only required when the stack is a client, and therefore is only enabled when STACK_CLIENT_MODE is enabled.

Stack API > ARP > Public Members > ARPIsResolved Function


ARPDeRegisterCallbacks Function

Contents | Index | Home
Previous | Up | Next
ARPDeRegisterCallbacks Function
C
BOOL ARPDeRegisterCallbacks(
    CHAR 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 ARPRegisterCallbacks call
Returns

TRUE - On success FALSE - Failure to indicate invalid reg_id

Stack API > ARP > Public Members > ARPDeRegisterCallbacks Function


ARPRegisterCallbacks Function

Contents | Index | Home
Previous | Up | Next
ARPRegisterCallbacks Function
C
CHAR ARPRegisterCallbacks(
    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

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

Stack API > ARP > Public Members > ARPRegisterCallbacks Function


ARPSendPkt Function

Contents | Index | Home
Previous | Up | Next
ARPSendPkt Function
C
BOOL ARPSendPkt(
    DWORD SrcIPAddr,
    DWORD DestIPAddr,
    BYTE op_req
);
Description

This function transmits and ARP request/reply to determine the hardware address of a given IP address (or) Announce self-address to all nodes in network. Extended for zeroconf protocol.

Preconditions

ARP packet is ready in the MAC buffer.

Parameters
Parameters | Description
SrcIPAddr | The Source IP-address
DestIPAddr | The Destination IP-Address
op_req | Operation Request (ARP_REQ/ARP_RESP)
Returns

TRUE - The ARP packet was generated properly FALSE - Not possible return value

Remarks

This API is to give control over AR-packet to external modules.

Stack API > ARP > Public Members > ARPSendPkt Function


arp_app_callbacks Structure

Contents | Index | Home
Previous | Up | Next
arp_app_callbacks Structure
C
struct arp_app_callbacks {
  BOOL used;
  void (* ARPPkt_notify)(DWORD SenderIPAddr, DWORD TargetIPAddr, MAC_ADDR* SenderMACAddr, MAC_ADDR* TargetMACAddr, BYTE op_req);
};
Description

This is record arp_app_callbacks.

Stack API > ARP > Public Members > arp_app_callbacks Structure


ARP_REQ Macro

Contents | Index | Home
Previous | Up | Next
ARP_REQ Macro
C
#define ARP_REQ 0x0001u        // Operation code indicating an ARP Request
Description

Operation code indicating an ARP Request

Stack API > ARP > Public Members > ARP_REQ Macro


ARP_RESP Macro

Contents | Index | Home
Previous | Up | Next
ARP_RESP Macro
C
#define ARP_RESP 0x0002u        // Operation code indicating an ARP Response
Description

Operation code indicating an ARP Response

Stack API > ARP > Public Members > ARP_RESP Macro


MAX_REG_APPS Macro

Contents | Index | Home
Previous | Up | Next
MAX_REG_APPS Macro
C
#define MAX_REG_APPS 2           // MAX num allowed registrations of Modules/Apps
Description

MAX num allowed registrations of Modules/Apps

Stack API > ARP > Public Members > MAX_REG_APPS Macro


ARP Stack Members

Contents | Index | Home
Previous | Up | Next
ARP Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
ARPInit | Initializes the ARP module.
ARPProcess | Processes an incoming ARP packet.
Module

ARP

Stack API > ARP > Stack Members


ARPInit Function

Contents | Index | Home
Previous | Up | Next
ARPInit Function
C
void ARPInit();
Description

Initializes the ARP module. Call this function once at boot to invalidate the cached lookup.

Preconditions

None

Returns

None

Remarks

This function is only required when the stack is a client, and therefore is only enabled when STACK_CLIENT_MODE is enabled.

Stack API > ARP > Stack Members > ARPInit Function


ARPProcess Function

Contents | Index | Home
Previous | Up | Next
ARPProcess Function
C
BOOL ARPProcess();
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
TRUE | All processing of this ARP packet is complete. Do not call again until a new ARP packet is waiting in the RX buffer.
FALSE | This function must be called again. More time is needed to send an ARP response.
Stack API > ARP > Stack Members > ARPProcess Function


ARP Internal Members

Contents | Index | Home
Previous | Up | Next
ARP Internal Members

The following functions and variables are designated as internal to the ARP module.

Functions
Name | Description
ARPPut | Writes an ARP packet to the MAC.
SwapARPPacket | Swaps endian-ness of header information in an ARP packet.
Macros
Name | Description
ARP_OPERATION_REQ | Operation code indicating an ARP Request
ARP_OPERATION_RESP | Operation code indicating an ARP Response
HW_ETHERNET | ARP Hardware type as defined by IEEE 802.3
ARP_IP | ARP IP packet type as defined by IEEE 802.3
Module

ARP

Variables
Name | Description
Cache | Cache for one ARP response
reg_apps | Call-Backs storage for MAX of two Modules/Apps // ARP packet structure typedef struct __attribute__((aligned(2), packed)) { WORD HardwareType; WORD Protocol; BYTE MACAddrLen; BYTE ProtocolLen; WORD Operation; MAC_ADDR SenderMACAddr; IP_ADDR SenderIPAddr; MAC_ADDR TargetMACAddr; IP_ADDR TargetIPAddr; } ARP_PACKET;
Stack API > ARP > Internal Members


ARPPut Function

Contents | Index | Home
Previous | Up | Next
ARPPut Function
C
static BOOL ARPPut(
    ARP_PACKET* packet
);
Description

Writes an ARP packet to the MAC.

Preconditions

None

Parameters
Parameters | Description
packet | A pointer to an ARP_PACKET structure with correct operation and target preconfigured.
Return Values
Return Values | Description
TRUE | The ARP packet was generated properly
FALSE | Not a possible return value
Stack API > ARP > Internal Members > ARPPut Function


SwapARPPacket Function

Contents | Index | Home
Previous | Up | Next
SwapARPPacket Function
C
void SwapARPPacket(
    ARP_PACKET* p
);
Description

Swaps endian-ness of header information in an ARP packet.

Preconditions

None

Parameters
Parameters | Description
p | The ARP packet to be swapped
Returns

None

Stack API > ARP > Internal Members > SwapARPPacket Function


ARP_OPERATION_REQ Macro

Contents | Index | Home
Previous | Up | Next
ARP_OPERATION_REQ Macro
C
#define ARP_OPERATION_REQ 0x0001u        // Operation code indicating an ARP Request
Description

Operation code indicating an ARP Request

Stack API > ARP > Internal Members > ARP_OPERATION_REQ Macro


ARP_OPERATION_RESP Macro

Contents | Index | Home
Previous | Up | Next
ARP_OPERATION_RESP Macro
C
#define ARP_OPERATION_RESP 0x0002u        // Operation code indicating an ARP Response
Description

Operation code indicating an ARP Response

Stack API > ARP > Internal Members > ARP_OPERATION_RESP Macro


HW_ETHERNET Macro

Contents | Index | Home
Previous | Up | Next
HW_ETHERNET Macro
C
#define HW_ETHERNET (0x0001u)    // ARP Hardware type as defined by IEEE 802.3
Description

ARP Hardware type as defined by IEEE 802.3

Stack API > ARP > Internal Members > HW_ETHERNET Macro


ARP_IP Macro

Contents | Index | Home
Previous | Up | Next
ARP_IP Macro
C
#define ARP_IP (0x0800u)    // ARP IP packet type as defined by IEEE 802.3
Description

ARP IP packet type as defined by IEEE 802.3

Stack API > ARP > Internal Members > ARP_IP Macro


Cache Variable

Contents | Index | Home
Previous | Up | Next
Cache Variable
C
NODE_INFO Cache;
Description

Cache for one ARP response

Stack API > ARP > Internal Members > Cache Variable


reg_apps Variable

Contents | Index | Home
Previous | Up | Next
reg_apps Variable
C
struct arp_app_callbacks reg_apps[MAX_REG_APPS];
Description

Call-Backs storage for MAX of two Modules/Apps

// ARP packet structure typedef struct __attribute__((aligned(2), packed)) { WORD HardwareType; WORD Protocol; BYTE MACAddrLen; BYTE ProtocolLen; WORD Operation; MAC_ADDR SenderMACAddr; IP_ADDR SenderIPAddr; MAC_ADDR TargetMACAddr; IP_ADDR TargetIPAddr; } ARP_PACKET;

Stack API > ARP > Internal Members > reg_apps Variable


Types

Contents | Index | Home
Previous | Up | Next
Types
Module

ARP

Structures
Name | Description
ARP_PACKET | ARP packet structure
Stack API > ARP > Types


ARP_PACKET Structure

Contents | Index | Home
Previous | Up | Next
ARP_PACKET Structure
C
typedef struct {
  WORD HardwareType;
  WORD Protocol;
  BYTE MACAddrLen;
  BYTE ProtocolLen;
  WORD Operation;
  MAC_ADDR SenderMACAddr;
  IP_ADDR SenderIPAddr;
  MAC_ADDR TargetMACAddr;
  IP_ADDR TargetIPAddr;
} ARP_PACKET;
Description

ARP packet structure

Members
Members | Description
WORD HardwareType; | Link-layer protocol type (Ethernet is 1).
WORD Protocol; | The upper-layer protocol issuing an ARP request (0x0800 for IPv4)..
BYTE MACAddrLen; | MAC address length (6).
BYTE ProtocolLen; | Length of addresses used in the upper-layer protocol (4).
WORD Operation; | The operation the sender is performing (ARP_REQ or ARP_RESP).
MAC_ADDR SenderMACAddr; | The sender's hardware (MAC) address.
IP_ADDR SenderIPAddr; | The sender's IP address.
MAC_ADDR TargetMACAddr; | The target node's hardware (MAC) address.
IP_ADDR TargetIPAddr; | The target node's IP address.
Stack API > ARP > Types > ARP_PACKET Structure


Berkeley (BSD) Sockets

Contents | Index | Home
Previous | Up | Next
Berkeley (BSD) Sockets

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.

Topics
Name | Description
BSD Wrapper Public Members | Functions and variables accessible by the stack application
BSD Wrapper Stack Members | Functions and variables intended to be accessed only by the stack
BSD Wrapper Internal Members | Functions and variables internal to the module
Stack API > BSD Sockets


BSD Wrapper Public Members

Contents | Index | Home
Previous | Up | Next
BSD Wrapper Public Members

The following functions and variables are available to the stack application.

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.
INADDR_ANY | IP address for server binding.
INVALID_TCP_PORT | Invalide 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
Module

Berkeley (BSD) Sockets

Structures
Name | Description
BSDSocket | Berkeley Socket structure
in_addr | in_addr structure
sockaddr | generic address structure for all address families
sockaddr_in | In the Internet address family
Types
Name | Description
SOCKADDR | generic address structure for all address families
SOCKADDR_IN | In the Internet address family
SOCKET | Socket descriptor
Stack API > BSD Sockets > Public Members


accept Function

Contents | Index | Home
Previous | Up | Next
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
Returns

If the accept function succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. Otherwise, the value INVALID_SOCKET is returned.

Remarks

None.

Stack API > BSD Sockets > Public Members > accept Function


AF_INET Macro

Contents | Index | Home
Previous | Up | Next
AF_INET Macro
C
#define AF_INET 2            // Internet Address Family - UDP, TCP, etc.
Description

Internet Address Family - UDP, TCP, etc.

Stack API > BSD Sockets > Public Members > AF_INET Macro


bind Function

Contents | Index | Home
Previous | Up | Next
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.

Remarks

None.

Stack API > BSD Sockets > Public Members > bind Function


BSDSocket Structure

Contents | Index | Home
Previous | Up | Next
BSDSocket Structure
C
struct BSDSocket {
  int SocketType;
  BSD_SCK_STATE bsdState;
  WORD localPort;
  WORD remotePort;
  DWORD remoteIP;
  int backlog;
  BOOL isServer;
  TCP_SOCKET SocketID;
};
Description

Berkeley Socket structure

Members
Members | Description
int SocketType; | Socket type
BSD_SCK_STATE bsdState; | Socket state
WORD localPort; | local port
WORD remotePort; | remote port
DWORD remoteIP; | remote IP
int backlog; | maximum number or client connection
BOOL isServer; | server/client check
TCP_SOCKET SocketID; | Socket ID
Stack API > BSD Sockets > Public Members > BSDSocket Structure


closesocket Function

Contents | Index | Home
Previous | Up | Next
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.

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.

Remarks

None.

Stack API > BSD Sockets > Public Members > closesocket Function


connect Function

Contents | Index | Home
Previous | Up | Next
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. For stream based socket, if the connection is not established yet, connect returns SOCKET_CNXN_IN_PROGRESS.

Remarks

None.

Stack API > BSD Sockets > Public Members > connect Function


gethostname Function

Contents | Index | Home
Previous | Up | Next
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.

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. On error, *name will be unmodified and no null terminator will be generated.

Remarks

None.

Stack API > BSD Sockets > Public Members > gethostname Function


in_addr Structure

Contents | Index | Home
Previous | Up | Next
in_addr Structure
C
struct in_addr {
  union {
    struct {
      BYTE s_b1, s_b2, s_b3, s_b4;
    } S_un_b;
    struct {
      WORD s_w1, s_w2;
    } S_un_w;
    DWORD S_addr;
  } S_un;
};
Description

in_addr structure

Members
Members
Description
union {
struct {
BYTE s_b1, s_b2, s_b3, s_b4;
} S_un_b;
struct {
WORD s_w1, s_w2;
} S_un_w;
DWORD S_addr;
} S_un;
union of IP address
struct {
BYTE s_b1, s_b2, s_b3, s_b4;
} S_un_b;
IP address in Byte
struct {
WORD s_w1, s_w2;
} S_un_w;
IP address in Word
DWORD S_addr;
IP address
Stack API > BSD Sockets > Public Members > in_addr Structure


INADDR_ANY Macro

Contents | Index | Home
Previous | Up | Next
INADDR_ANY Macro
C
#define INADDR_ANY 0x00000000u    // IP address for server binding.
Description

IP address for server binding.

Stack API > BSD Sockets > Public Members > INADDR_ANY Macro


INVALID_TCP_PORT Macro

Contents | Index | Home
Previous | Up | Next
INVALID_TCP_PORT Macro
C
#define INVALID_TCP_PORT (0L)  //Invalide TCP port
Description

Invalide TCP port

Stack API > BSD Sockets > Public Members > INVALID_TCP_PORT Macro


IP_ADDR_ANY Macro

Contents | Index | Home
Previous | Up | Next
IP_ADDR_ANY Macro
C
#define IP_ADDR_ANY 0u            // IP Address for server binding
Description

IP Address for server binding

Stack API > BSD Sockets > Public Members > IP_ADDR_ANY Macro


IPPROTO_IP Macro

Contents | Index | Home
Previous | Up | Next
IPPROTO_IP Macro
C
#define IPPROTO_IP 0   // Indicates IP pseudo-protocol.
Description

Indicates IP pseudo-protocol.

Stack API > BSD Sockets > Public Members > IPPROTO_IP Macro


IPPROTO_TCP Macro

Contents | Index | Home
Previous | Up | Next
IPPROTO_TCP Macro
C
#define IPPROTO_TCP 6   // Indicates TCP for the internet address family.
Description

Indicates TCP for the internet address family.

Stack API > BSD Sockets > Public Members > IPPROTO_TCP Macro


IPPROTO_UDP Macro

Contents | Index | Home
Previous | Up | Next
IPPROTO_UDP Macro
C
#define IPPROTO_UDP 17  // Indicates UDP for the internet address family.
Description

Indicates UDP for the internet address family.

Stack API > BSD Sockets > Public Members > IPPROTO_UDP Macro


listen Function

Contents | Index | Home
Previous | Up | Next
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_PURPOSE_BERKELEY_SERVER type TCP socket to be allocated in the TCPSocketInitializer[] in TCPIPConfig.h. Also, ensure that BSD_SOCKET_COUNT (also in TCPIPConfig.h) is greater than the backlog by at least 1 (more if you have other BSD sockets in use).
Returns

Returns 0 on success, else return SOCKET_ERROR.

Remarks

None

Stack API > BSD Sockets > Public Members > listen Function


recv Function

Contents | Index | Home
Previous | Up | Next
recv Function
C
int recv(
    SOCKET s,
    char* buf,
    int len,
    int flags
);
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 value of zero indicates no data available. A return value of SOCKET_ERROR (-1) indicates an error condition. A return value of SOCKET_DISCONNECTED indicates the connection no longer exists.

Remarks

None.

Stack API > BSD Sockets > Public Members > recv Function


recvfrom Function

Contents | Index | Home
Previous | Up | Next
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.
Returns

If recvfrom is successful, the number of bytes copied to application buffer buf is returned. A value of zero indicates no data available. A return value of SOCKET_ERROR (-1) indicates an error condition.

Remarks

None.

Stack API > BSD Sockets > Public Members > recvfrom Function


send Function

Contents | Index | Home
Previous | Up | Next
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. In case of error, returns SOCKET_ERROR. a zero indicates no data send.

Remarks

None.

Stack API > BSD Sockets > Public Members > send Function


sendto Function

Contents | Index | Home
Previous | Up | Next
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.

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

Remarks

None.

Stack API > BSD Sockets > Public Members > sendto Function


SOCK_DGRAM Macro

Contents | Index | Home
Previous | Up | Next
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.

Stack API > BSD Sockets > Public Members > SOCK_DGRAM Macro


SOCK_STREAM Macro

Contents | Index | Home
Previous | Up | Next
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.

Stack API > BSD Sockets > Public Members > SOCK_STREAM Macro


sockaddr Structure

Contents | Index | Home
Previous | Up | Next
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
Stack API > BSD Sockets > Public Members > sockaddr Structure


SOCKADDR Type

Contents | Index | Home
Previous | Up | Next
SOCKADDR Type
C
typedef struct sockaddr SOCKADDR;
Description

generic address structure for all address families

Stack API > BSD Sockets > Public Members > SOCKADDR Type


sockaddr_in Structure

Contents | Index | Home
Previous | Up | Next
sockaddr_in Structure
C
struct sockaddr_in {
  short sin_family;
  WORD 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.
WORD sin_port; | Internet Protocol (IP) port.
struct in_addr sin_addr; | IP address in network byte order.
char sin_zero[8]; | Padding to make structure the same size as SOCKADDR.
Stack API > BSD Sockets > Public Members > sockaddr_in Structure


SOCKADDR_IN Type

Contents | Index | Home
Previous | Up | Next
SOCKADDR_IN Type
C
typedef struct sockaddr_in SOCKADDR_IN;
Description

In the Internet address family

Stack API > BSD Sockets > Public Members > SOCKADDR_IN Type


socket Function

Contents | Index | Home
Previous | Up | Next
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. INVALID_SOCKET in case of error.

Remarks

None.

Stack API > BSD Sockets > Public Members > socket Function


SOCKET Type

Contents | Index | Home
Previous | Up | Next
SOCKET Type
C
typedef BYTE SOCKET;
Description

Socket descriptor

Stack API > BSD Sockets > Public Members > SOCKET Type


SOCKET_CNXN_IN_PROGRESS Macro

Contents | Index | Home
Previous | Up | Next
SOCKET_CNXN_IN_PROGRESS Macro
C
#define SOCKET_CNXN_IN_PROGRESS (-2) //Socket connection state.
Description

Socket connection state.

Stack API > BSD Sockets > Public Members > SOCKET_CNXN_IN_PROGRESS Macro


SOCKET_DISCONNECTED Macro

Contents | Index | Home
Previous | Up | Next
SOCKET_DISCONNECTED Macro
C
#define SOCKET_DISCONNECTED (-3) //Socket disconnected
Description

Socket disconnected

Stack API > BSD Sockets > Public Members > SOCKET_DISCONNECTED Macro


SOCKET_ERROR Macro

Contents | Index | Home
Previous | Up | Next
SOCKET_ERROR Macro
C
#define SOCKET_ERROR (-1) //Socket error
Description

Socket error

Stack API > BSD Sockets > Public Members > SOCKET_ERROR Macro


BSD Wrapper Stack Members

Contents | Index | Home
Previous | Up | Next
BSD Wrapper Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
BerkeleySocketInit | Initializes the Berkeley socket structure array.
Module

Berkeley (BSD) Sockets

Stack API > BSD Sockets > Stack Members


BerkeleySocketInit Function

Contents | Index | Home
Previous | Up | Next
BerkeleySocketInit Function
C
void BerkeleySocketInit();
Description

This function initializes the Berkeley socket array. This function should be called before any BSD socket call.

Preconditions

None.

Returns

None

Remarks

None.

Stack API > BSD Sockets > Stack Members > BerkeleySocketInit Function


BSD Wrapper Internal Members

Contents | Index | Home
Previous | Up | Next
BSD Wrapper Internal Members

The following functions and variables are designated as internal to the module.

Enumerations
Name | Description
BSD_SCK_STATE | Berkeley Socket (BSD) states
Functions
Name | Description
HandlePossibleTCPDisconnection | Internal function that checks for asynchronous TCP connection state changes and resynchs the BSD socket descriptor state to match.
Module

Berkeley (BSD) Sockets

Variables
Name | Description
BSDSocketArray | Array of BSDSocket elements; used to track all socket state and connection information.
gAutoPortNumber | Contains the next local port number to associate with a socket.
Stack API > BSD Sockets > Internal Members


BSD_SCK_STATE Enumeration

Contents | Index | Home
Previous | Up | Next
BSD_SCK_STATE Enumeration
C
typedef enum {
  SKT_CLOSED,
  SKT_CREATED,
  SKT_BOUND,
  SKT_BSD_LISTEN,
  SKT_LISTEN,
  SKT_IN_PROGRESS,
  SKT_EST,
  SKT_DISCONNECTED
} BSD_SCK_STATE;
Description

Berkeley Socket (BSD) states

Members
Members | Description
SKT_CLOSED | Socket closed state indicating a free descriptor
SKT_CREATED | Socket created state for TCP and UDP sockets
SKT_BOUND | Socket bound state for TCP and UDP sockets
SKT_BSD_LISTEN | Listening state for TCP BSD listener handle "socket
SKT_LISTEN | TCP server listen state
SKT_IN_PROGRESS | TCP client connection in progress state
SKT_EST | TCP client or server established state
SKT_DISCONNECTED | TCP client or server no longer connected to the remote host (but was historically)
Stack API > BSD Sockets > Internal Members > BSD_SCK_STATE Enumeration


BSDSocketArray Variable

Contents | Index | Home
Previous | Up | Next
BSDSocketArray Variable
C
struct BSDSocket BSDSocketArray[BSD_SOCKET_COUNT];
Description

Array of BSDSocket elements; used to track all socket state and connection information.

Stack API > BSD Sockets > Internal Members > BSDSocketArray Variable


gAutoPortNumber Variable

Contents | Index | Home
Previous | Up | Next
gAutoPortNumber Variable
C
WORD gAutoPortNumber = 1024;
Description

Contains the next local port number to associate with a socket.

Stack API > BSD Sockets > Internal Members > gAutoPortNumber Variable


HandlePossibleTCPDisconnection Function

Contents | Index | Home
Previous | Up | Next
HandlePossibleTCPDisconnection Function
C
static BOOL HandlePossibleTCPDisconnection(
    SOCKET s
);
Description

Internal function that checks for asynchronous TCP connection state changes and resynchs the BSD socket descriptor state to match.

Preconditions

None

Parameters
Parameters | Description
s | TCP type socket descriptor returned from a previous call to socket. This socket must be in the SKT_LISTEN, SKT_IN_PROGRESS, SKT_EST, or SKT_DISCONNECTED states.
Returns

TRUE - Socket is disconnected FALSE - Socket is

Stack API > BSD Sockets > Internal Members > HandlePossibleTCPDisconnection Function


DNS Client

Contents | Index | Home
Previous | Up | Next
DNS Client

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.

DNS resolution operations follow a simple state machine, as indicated in the diagram below.

Topics
Name | Description
DNS Public Members | Functions and variables accessible by the stack application
DNS Internal Members | Functions and variables internal to the DNS module
Stack API > DNS


DNS Public Members

Contents | Index | Home
Previous | Up | Next
DNS Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
DNSBeginUsage | Claims access to the DNS module.
DNSEndUsage | Releases control of the DNS module.
DNSResolve | Begins resolution of an address.
DNSResolveROM | Begins resolution of an address.
DNSIsResolved | Determines if the DNS resolution is complete and provides the IP.
Macros
Name | Description
DNS_TYPE_A | Constant for record type in DNSResolve. Indicates an A (standard address) record.
DNS_TYPE_MX | Constant for record type in DNSResolve. Indicates an MX (mail exchanger) record.
Module

DNS Client

Stack API > DNS > Public Members


DNSBeginUsage Function

Contents | Index | Home
Previous | Up | Next
DNSBeginUsage Function
C
BOOL DNSBeginUsage();
Description

This function acts as a semaphore to obtain usage of the DNS module. Call this function and ensure that it returns TRUE before calling any other DNS APIs. Call DNSEndUsage when this application no longer needs the DNS module so that other applications may make use of it.

Preconditions

Stack is initialized.

Return Values
Return Values | Description
TRUE | No other DNS resolutions are in progress and the calling application has sucessfully taken ownership of the DNS module
FALSE | The DNS module is currently in use. Yield to the stack and attempt this call again later.
Remarks

Ensure that DNSEndUsage 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.

Stack API > DNS > Public Members > DNSBeginUsage Function


DNSEndUsage Function

Contents | Index | Home
Previous | Up | Next
DNSEndUsage Function
C
BOOL DNSEndUsage();
Description

This function acts as a semaphore to obtain usage 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.

Preconditions

DNSBeginUsage returned TRUE on a previous call.

Return Values
Return Values | Description
TRUE | The address to the host name was successfully resolved.
FALSE | The DNS failed or the address does not exist.
Remarks

Ensure that DNSEndUsage 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.

Stack API > DNS > Public Members > DNSEndUsage Function


DNSResolve Function

Contents | Index | Home
Previous | Up | Next
DNSResolve Function
C
void DNSResolve(
    BYTE* HostName,
    BYTE Type
);
Description

This function attempts to resolve a host name to an IP address. When called, it starts the DNS state machine. Call DNSIsResolved 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

DNSBeginUsage returned TRUE on a previous call.

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

None

Remarks

This function requires access to one UDP socket. If none are available, MAX_UDP_SOCKETS may need to be increased.

Stack API > DNS > Public Members > DNSResolve Function


DNSResolveROM Function

Contents | Index | Home
Previous | Up | Next
DNSResolveROM Function
C
void DNSResolveROM(
    ROM BYTE* Hostname,
    BYTE Type
);
Description

This function attempts to resolve a host name to an IP address. When called, it starts the DNS state machine. Call DNSIsResolved 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

DNSBeginUsage returned TRUE on a previous call.

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

None

Remarks

This function requires access to one UDP socket. If none are available, MAX_UDP_SOCKETS may need to be increased.

This function is aliased to DNSResolve on non-PIC18 platforms.

Stack API > DNS > Public Members > DNSResolveROM Function


DNSIsResolved Function

Contents | Index | Home
Previous | Up | Next
DNSIsResolved Function
C
BOOL DNSIsResolved(
    IP_ADDR* 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

DNSResolve or DNSResolveROM has been called.

Parameters
Parameters | Description
HostIP | A pointer to an IP_ADDR structure in which to store the resolved IP address once resolution is complete.
Return Values
Return Values | Description
TRUE | The DNS client has obtained an IP, or the DNS process has encountered an error. HostIP will be 0.0.0.0 on error. Possible errors include server timeout (i.e. DNS server not available), hostname not in the DNS, or DNS server errors.
FALSE | The resolution process is still in progress.
Stack API > DNS > Public Members > DNSIsResolved Function


DNS_TYPE_A Macro

Contents | Index | Home
Previous | Up | Next
DNS_TYPE_A Macro
C
#define DNS_TYPE_A (1u)        // Constant for record type in DNSResolve.  Indicates an A (standard address) record.
Description

Constant for record type in DNSResolve. Indicates an A (standard address) record.

Stack API > DNS > Public Members > DNS_TYPE_A Macro


DNS_TYPE_MX Macro

Contents | Index | Home
Previous | Up | Next
DNS_TYPE_MX Macro
C
#define DNS_TYPE_MX (15u)        // Constant for record type in DNSResolve.  Indicates an MX (mail exchanger) record.
Description

Constant for record type in DNSResolve. Indicates an MX (mail exchanger) record.

Stack API > DNS > Public Members > DNS_TYPE_MX Macro


DNS Internal Members

Contents | Index | Home
Previous | Up | Next
DNS Internal Members

The following functions and variables are designated as internal to the DNS module.

Functions
Name | Description
DNSPutString | Writes a string to the DNS socket.
DNSPutROMString | Writes a ROM string to the DNS socket.
DNSDiscardName | Reads a name string or string pointer from the DNS socket and discards it.
Macros
Name | Description
DNS_PORT | Default port for DNS resolutions
DNS_TIMEOUT | Elapsed time after which a DNS resolution is considered to have timed out
Module

DNS Client

Structures
Name | Description
DNS_HEADER | Structure for the DNS header
Variables
Name | Description
DNSHostName | Host name in RAM to look up
DNSHostNameROM | Host name in ROM to look up
Flags | Stores various flags for the UDP module
RecordType | Record type being queried
ResolvedInfo | Node information about the resolved node
smDNS | State machine for a DNS query
Stack API > DNS > Internal Members


DNSPutString Function

Contents | Index | Home
Previous | Up | Next
DNSPutString Function
C
static void DNSPutString(
    BYTE* String
);
Description

This function writes a string to the DNS socket, ensuring that it is properly formatted.

Preconditions

UDP socket is obtained and ready for writing.

Parameters
Parameters | Description
String | the string to write to the UDP socket.
Returns

None

Stack API > DNS > Internal Members > DNSPutString Function


DNSPutROMString Function

Contents | Index | Home
Previous | Up | Next
DNSPutROMString Function
C
static void DNSPutROMString(
    ROM BYTE* String
);
Description

This function writes a string to the DNS socket, ensuring that it is properly formatted.

Preconditions

UDP socket is obtained and ready for writing.

Parameters
Parameters | Description
String | the string to write to the UDP socket.
Returns

None

Remarks

This function is aliased to DNSPutString on non-PIC18 platforms.

Stack API > DNS > Internal Members > DNSPutROMString Function


DNS_PORT Macro

Contents | Index | Home
Previous | Up | Next
DNS_PORT Macro
C
#define DNS_PORT 53u                    // Default port for DNS resolutions
Description

Default port for DNS resolutions

Stack API > DNS > Internal Members > DNS_PORT Macro


DNS_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
DNS_TIMEOUT Macro
C
#define DNS_TIMEOUT (TICK_SECOND*1)        // Elapsed time after which a DNS resolution is considered to have timed out
Description

Elapsed time after which a DNS resolution is considered to have timed out

Stack API > DNS > Internal Members > DNS_TIMEOUT Macro


DNSHostName Variable

Contents | Index | Home
Previous | Up | Next
DNSHostName Variable
C
BYTE * DNSHostName;
Description

Host name in RAM to look up

Stack API > DNS > Internal Members > DNSHostName Variable


DNSHostNameROM Variable

Contents | Index | Home
Previous | Up | Next
DNSHostNameROM Variable
C
ROM BYTE * DNSHostNameROM;
Description

Host name in ROM to look up

Stack API > DNS > Internal Members > DNSHostNameROM Variable


Flags Variable

Contents | Index | Home
Previous | Up | Next
Flags Variable
C
struct {
  unsigned char bFirstRead : 1;
  unsigned char bWasDiscarded : 1;
} Flags;
Description

Stores various flags for the UDP module

Members
Members | Description
unsigned char bFirstRead : 1; | No data has been read from this segment yet
unsigned char bWasDiscarded : 1; | The data in this segment has been discarded
Stack API > DNS > Internal Members > Flags Variable


RecordType Variable

Contents | Index | Home
Previous | Up | Next
RecordType Variable
C
BYTE RecordType;
Description

Record type being queried

Stack API > DNS > Internal Members > RecordType Variable


ResolvedInfo Variable

Contents | Index | Home
Previous | Up | Next
ResolvedInfo Variable
C
NODE_INFO ResolvedInfo;
Description

Node information about the resolved node

Stack API > DNS > Internal Members > ResolvedInfo Variable


smDNS Variable

Contents | Index | Home
Previous | Up | Next
smDNS Variable
C
enum {
  DNS_START = 0,
  DNS_ARP_START_RESOLVE,
  DNS_ARP_RESOLVE,
  DNS_OPEN_SOCKET,
  DNS_QUERY,
  DNS_GET_RESULT,
  DNS_FAIL,
  DNS_DONE
} smDNS;
Description

State machine for a DNS query

Members
Members | Description
DNS_START = 0 | Initial state to reset client state variables
DNS_ARP_START_RESOLVE | Send ARP resolution of DNS server or gateway MAC address
DNS_ARP_RESOLVE | Wait for response to ARP request
DNS_OPEN_SOCKET | Open UDP socket
DNS_QUERY | Send DNS query to DNS server
DNS_GET_RESULT | Wait for response from DNS server
DNS_FAIL | ARP or DNS server not responding
DNS_DONE | DNS query is finished
Stack API > DNS > Internal Members > smDNS Variable


DNS_HEADER Structure

Contents | Index | Home
Previous | Up | Next
DNS_HEADER Structure
C
typedef struct {
  WORD_VAL TransactionID;
  WORD_VAL Flags;
  WORD_VAL Questions;
  WORD_VAL Answers;
  WORD_VAL AuthoritativeRecords;
  WORD_VAL AdditionalRecords;
} DNS_HEADER;
Description

Structure for the DNS header

Stack API > DNS > Internal Members > DNS_HEADER Structure


DNSDiscardName Function

Contents | Index | Home
Previous | Up | Next
DNSDiscardName Function
C
static void DNSDiscardName();
Description

This function reads a name string from the DNS socket. Each string consists of a series of labels. Each label consists of a length prefix byte, followed by the label bytes. At the end of the string, a zero length label is found as termination. If name compression is used, this function will automatically detect the pointer and discard it.

Preconditions

UDP socket is obtained and ready for reading a DNS name

Returns

None

Stack API > DNS > Internal Members > DNSDiscardName Function


Dynamic DNS Client

Contents | Index | Home
Previous | Up | Next
Dynamic DNS Client

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 [image] DynDNS.org, [image] No-IP.com, and [image] 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.

Topics
Name | Description
Dynamic DNS Public Members | Functions and variables accessed by the stack application
Dynamic DNS Stack Members | Functions and variables intended to be accessed only by the stack
Dynamic DNS Internal Members | Functions and variables internal to the Dynamic DNS module
Stack API > Dynamic DNS Client


Dynamic DNS Public Members

Contents | Index | Home
Previous | Up | Next
Dynamic DNS Public Members

These functions and variables are meant to be called by your stack application.

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
DDNSForceUpdate | Forces an immediate DDNS update
DDNSGetLastIP | Returns the last known external IP address of the device.
DDNSGetLastStatus | Returns the status of the most recent update.
DDNSSetService | Selects a pre-configured Dynamic DNS service
Module

Dynamic DNS Client

Structures
Name | Description
DDNS_POINTERS | Configuration parameters for the Dynamic DNS Client
Variables
Name | Description
DDNSClient | Configuration parameters for the module
Stack API > Dynamic DNS Client > Public Members


DDNS_POINTERS Structure

Contents | Index | Home
Previous | Up | Next
DDNS_POINTERS Structure
C
typedef struct {
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } CheckIPServer;
  WORD CheckIPPort;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } UpdateServer;
  WORD UpdatePort;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } Username;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } Password;
  union {
    BYTE * szRAM;
    ROM BYTE * 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 ROM. (Where [field name] is one of the parameters below.)

If a ROM string is specified, DDNSClient.ROMPointers.[field name] must also be set to 1 to indicate that this field should be retrieved from ROM 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 ROM instead of RAM.
Stack API > Dynamic DNS Client > Public Members > DDNS_POINTERS Structure


DDNS_SERVICES Enumeration

Contents | Index | Home
Previous | Up | Next
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
Stack API > Dynamic DNS Client > Public Members > DDNS_SERVICES Enumeration


DDNS_STATUS Enumeration

Contents | Index | Home
Previous | Up | Next
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_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.
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_INVALID | DDNS Client data is not valid.
DDNS_STATUS_UNKNOWN | DDNS client has not yet been executed with this configuration.
Stack API > Dynamic DNS Client > Public Members > DDNS_STATUS Enumeration


DDNSClient Variable

Contents | Index | Home
Previous | Up | Next
DDNSClient Variable
C
DDNS_POINTERS DDNSClient;
Description

Configuration parameters for the module

Stack API > Dynamic DNS Client > Public Members > DDNSClient Variable


DDNSForceUpdate Function

Contents | Index | Home
Previous | Up | Next
DDNSForceUpdate Function
C
void DDNSForceUpdate();
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

DDNSInit must have been called.

Returns

None

Stack API > Dynamic DNS Client > Public Members > DDNSForceUpdate Function


DDNSGetLastIP Function

Contents | Index | Home
Previous | Up | Next
DDNSGetLastIP Function
C
IP_ADDR DDNSGetLastIP();
Description

This function returns the last known external IP address of the device.

Preconditions

None

Returns

The last known external IP address of the device.

Stack API > Dynamic DNS Client > Public Members > DDNSGetLastIP Function


DDNSGetLastStatus Function

Contents | Index | Home
Previous | Up | Next
DDNSGetLastStatus Function
C
DDNS_STATUS DDNSGetLastStatus();
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.

Stack API > Dynamic DNS Client > Public Members > DDNSGetLastStatus Function


DDNSSetService Function

Contents | Index | Home
Previous | Up | Next
DDNSSetService Function
C
void DDNSSetService(
    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

Stack API > Dynamic DNS Client > Public Members > DDNSSetService Function


Dynamic DNS Stack Members

Contents | Index | Home
Previous | Up | Next
Dynamic DNS Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
DDNSInit | Initializes the Dynamic DNS module.
DDNSTask | Dynamic DNS client task/state machine.
Module

Dynamic DNS Client

Stack API > Dynamic DNS Client > Stack Members


DDNSInit Function

Contents | Index | Home
Previous | Up | Next
DDNSInit Function
C
void DDNSInit();
Description

This function initializes the Dynamic DNS client. It clears the DDNSClient pointers structure, and tells the module to attempt the first update after 15 seconds have elapsed (so as to allow the DHCP configuration to stabalize).

Preconditions

None

Returns

None

Remarks

This function is called only one during lifetime of the application.

Stack API > Dynamic DNS Client > Stack Members > DDNSInit Function


DDNSTask Function

Contents | Index | Home
Previous | Up | Next
DDNSTask Function
C
void DDNSTask();
Description

This function performs the background tasks of the Dynamic DNS Client. Once the DDNSPointers structure is configured, this task attempt to update the Dynamic DNS hostname on a periodic schedule.

The task first accesses the CheckIP server to determine the device's current external IP address. If the IP address has changed, it issues an update command to the dynamic DNS service to propagate the change. This sequence executes whenever dwUpdateAt elapses, which by default is every 10 minutes, or when an update is forced.

Preconditions

DDNSInit() has been called.

Returns

None

Remarks

This function acts as a task (similar to one in an RTOS). It performs its task in a co-operative manner, and the main application must call this function periodically to ensure that its tasks get executed in a timely fashion.

Stack API > Dynamic DNS Client > Stack Members > DDNSTask Function


Dynamic DNS Internal Members

Contents | Index | Home
Previous | Up | Next
Dynamic DNS Internal Members

The following functions and variables are designated as internal to the Dynamic DNS module.

Macros
Name | Description
DDNS_CHECKIP_SERVER | Default CheckIP server for determining current IP address
DDNS_DEFAULT_PORT | Default port for CheckIP server
Module

Dynamic DNS Client

Variables
Name | Description
bForceUpdate | Indicates that the update should be done regardless of whether or not the IP changed. Use this flag when the user/pass/hostname have changed.
ddnsServiceHosts | Host names for various Dynamic DNS services
ddnsServicePorts | Port numbers for various Dynamic DNS services
dwUpdateAt | Indicates when the next CheckIP should be done
lastKnownIP | Last known IP address of this device
lastStatus | Status response from last update
_checkIpSrvrResponse | Delimiter to locate IP address from CheckIP server
_updateIpSrvrResponse | Response codes from DynDNS Update Server
Stack API > Dynamic DNS Client > Internal Members


bForceUpdate Variable

Contents | Index | Home
Previous | Up | Next
bForceUpdate Variable
C
BOOL bForceUpdate;
Description

Indicates that the update should be done regardless of whether or not the IP changed. Use this flag when the user/pass/hostname have changed.

Stack API > Dynamic DNS Client > Internal Members > bForceUpdate Variable


ddnsServiceHosts Variable

Contents | Index | Home
Previous | Up | Next
ddnsServiceHosts Variable
C
ROM char * ROM ddnsServiceHosts[];
Description

Host names for various Dynamic DNS services

Stack API > Dynamic DNS Client > Internal Members > ddnsServiceHosts Variable


ddnsServicePorts Variable

Contents | Index | Home
Previous | Up | Next
ddnsServicePorts Variable
C
ROM WORD ddnsServicePorts[] = { 80, 80, 80, };
Description

Port numbers for various Dynamic DNS services

Stack API > Dynamic DNS Client > Internal Members > ddnsServicePorts Variable


dwUpdateAt Variable

Contents | Index | Home
Previous | Up | Next
dwUpdateAt Variable
C
DWORD dwUpdateAt;
Description

Indicates when the next CheckIP should be done

Stack API > Dynamic DNS Client > Internal Members > dwUpdateAt Variable


lastKnownIP Variable

Contents | Index | Home
Previous | Up | Next
lastKnownIP Variable
C
IP_ADDR lastKnownIP;
Description

Last known IP address of this device

Stack API > Dynamic DNS Client > Internal Members > lastKnownIP Variable


lastStatus Variable

Contents | Index | Home
Previous | Up | Next
lastStatus Variable
C
DDNS_STATUS lastStatus;
Description

Status response from last update

Stack API > Dynamic DNS Client > Internal Members > lastStatus Variable


_checkIpSrvrResponse Variable

Contents | Index | Home
Previous | Up | Next
_checkIpSrvrResponse Variable
C
ROM BYTE _checkIpSrvrResponse[] = "Address:";
Description

Delimiter to locate IP address from CheckIP server

Stack API > Dynamic DNS Client > Internal Members > _checkIpSrvrResponse Variable


_updateIpSrvrResponse Variable

Contents | Index | Home
Previous | Up | Next
_updateIpSrvrResponse Variable
C
ROM char* _updateIpSrvrResponse[] = { "good", "nochg", "abuse", "badsys", "badagent", "badauth", "!donator", "notfqdn", "nohost", "!yours", "numhost", "dnserr", "911", };
Description

Response codes from DynDNS Update Server

Stack API > Dynamic DNS Client > Internal Members > _updateIpSrvrResponse Variable


DDNS_CHECKIP_SERVER Macro

Contents | Index | Home
Previous | Up | Next
DDNS_CHECKIP_SERVER Macro
C
#define DDNS_CHECKIP_SERVER (ROM BYTE*)"checkip.dyndns.com"        // Default CheckIP server for determining current IP address
Description

Default CheckIP server for determining current IP address

Stack API > Dynamic DNS Client > Internal Members > DDNS_CHECKIP_SERVER Macro


DDNS_DEFAULT_PORT Macro

Contents | Index | Home
Previous | Up | Next
DDNS_DEFAULT_PORT Macro
C
#define DDNS_DEFAULT_PORT (80u)                                // Default port for CheckIP server
Description

Default port for CheckIP server

Stack API > Dynamic DNS Client > Internal Members > DDNS_DEFAULT_PORT Macro


Hashes

Contents | Index | Home
Previous | Up | Next
Hashes

The Hashes module calculates MD5 and/or SHA-1 hash sums of data. Hash sums are one-way digest functions, meaning that the original message cannot be derived from the hash of the message. Collisions, while exceedingly rare, do exist. However, they are extremely difficult to create.

Hash functions are generally used for message integrity and authentication purposes. They are used extensively by encryption protocols such as SSL to verify that a message has not been tampered with during transit.

The following flow diagram demonstrates how to use this module.

To use the hash functions, first declare a HASH_SUM structure and pass a pointer to it to either MD5Initialize or SHA1Initialize. Then, call HashAddData or HashAddROMData as many times as are necessary to provide all the data to the hash. Call MD5Calculate or SHA1Calculate at any time to obtain the hash sum up to the current point. After calculation, continue adding data and repeating this process as many times as necessary.

Topics
Name | Description
Hashes Public Members | Functions and variables accessible by the stack application
Hashes Stack Members | Functions and variables intended to be accessed only by the stack
Hashes Internal Members | Functions and variables internal to the Hashes module
Stack API > Hashes


Hashes Public Members

Contents | Index | Home
Previous | Up | Next
Hashes Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
HashAddData | Adds data to the hash sum.
HashAddROMData | Adds data to the hash sum.
MD5Calculate | Calculates an MD5 hash
MD5Initialize | Initializes a new MD5 hash.
SHA1Calculate | Calculates a SHA-1 hash
SHA1Initialize | Initializes a new SHA-1 hash.
Module

Hashes

Structures
Name | Description
HASH_SUM | Context storage for a hash operation
Stack API > Hashes > Public Members


HashAddData Function

Contents | Index | Home
Previous | Up | Next
HashAddData Function
C
void HashAddData(
    HASH_SUM* theSum,
    BYTE* data,
    WORD len
);
Description

Adds data to the hash sum.

Preconditions

The hash sum has already been initialized

Parameters
Parameters | Description
theSum | hash context state
data | the data to be added to the hash sum
len | length of data
Returns

None

Remarks

This function calls the appropriate hashing function based on the hash typed defined in theSum.

Stack API > Hashes > Public Members > HashAddData Function


HashAddROMData Function

Contents | Index | Home
Previous | Up | Next
HashAddROMData Function
C
void HashAddROMData(
    HASH_SUM* theSum,
    ROM BYTE* data,
    WORD len
);
Description

Adds data to the hash sum.

Preconditions

The hash sum has already been initialized

Parameters
Parameters | Description
theSum | hash context state
data | the data to be added to the hash sum
len | length of data
Returns

None

Remarks

This function calls the appropriate hashing function based on the hash typed defined in theSum.

This function is aliased to HashAddData on non-PIC18 platforms.

Stack API > Hashes > Public Members > HashAddROMData Function


MD5Calculate Function

Contents | Index | Home
Previous | Up | Next
MD5Calculate Function
C
void MD5Calculate(
    HASH_SUM* theSum,
    BYTE* result
);
Description

This function calculates the hash sum of all input data so far. It is non-destructive to the hash context, so more data may be added after this function is called.

Preconditions

The hash context has been properly initialized.

Parameters
Parameters | Description
theSum | the current hash context
result | 16 byte array in which to store the resulting hash
Returns

None

Stack API > Hashes > Public Members > MD5Calculate Function


MD5Initialize Function

Contents | Index | Home
Previous | Up | Next
MD5Initialize Function
C
void MD5Initialize(
    HASH_SUM* theSum
);
Description

Initializes a new MD5 hash.

Preconditions

None

Parameters
Parameters | Description
theSum | pointer to the allocated HASH_SUM object to initialize as MD5
Returns

None

Stack API > Hashes > Public Members > MD5Initialize Function


SHA1Calculate Function

Contents | Index | Home
Previous | Up | Next
SHA1Calculate Function
C
void SHA1Calculate(
    HASH_SUM* theSum,
    BYTE* result
);
Description

This function calculates the hash sum of all input data so far. It is non-destructive to the hash context, so more data may be added after this function is called.

Preconditions

The hash context has been properly initialized.

Parameters
Parameters | Description
theSum | the current hash context
result | 20 byte array in which to store the resulting hash
Returns

None

Stack API > Hashes > Public Members > SHA1Calculate Function


SHA1Initialize Function

Contents | Index | Home
Previous | Up | Next
SHA1Initialize Function
C
void SHA1Initialize(
    HASH_SUM* theSum
);
Description

Initializes a new SHA-1 hash.

Preconditions

None

Parameters
Parameters | Description
theSum | pointer to the allocated HASH_SUM object to initialize as SHA-1
Returns

None

Stack API > Hashes > Public Members > SHA1Initialize Function


HASH_SUM Structure

Contents | Index | Home
Previous | Up | Next
HASH_SUM Structure
C
typedef struct {
  DWORD h0;
  DWORD h1;
  DWORD h2;
  DWORD h3;
  DWORD h4;
  DWORD bytesSoFar;
  BYTE partialBlock[64];
  HASH_TYPE hashType;
} HASH_SUM;
Description

Context storage for a hash operation

Members
Members | Description
DWORD h0; | Hash state h0
DWORD h1; | Hash state h1
DWORD h2; | Hash state h2
DWORD h3; | Hash state h3
DWORD h4; | Hash state h4
DWORD bytesSoFar; | Total number of bytes hashed so far
BYTE partialBlock[64]; | Beginning of next 64 byte block
HASH_TYPE hashType; | Type of hash being calculated
Stack API > Hashes > Public Members > HASH_SUM Structure


Hashes Stack Members

Contents | Index | Home
Previous | Up | Next
Hashes Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
MD5AddROMData | Adds data to an MD5 hash calculation.
SHA1AddROMData | Adds data to a SHA-1 hash calculation.
SHA1AddData | Adds data to a SHA-1 hash calculation.
MD5AddData | Adds data to an MD5 hash calculation.
Module

Hashes

Stack API > Hashes > Stack Members


MD5AddROMData Function

Contents | Index | Home
Previous | Up | Next
MD5AddROMData Function
C
void MD5AddROMData(
    HASH_SUM* theSum,
    ROM BYTE* data,
    WORD len
);
Description

Adds data to an MD5 hash calculation.

Preconditions

The hash context has already been initialized.

Parameters
Parameters | Description
theSum | a pointer to the hash context structure
data | the data to add to the hash
len | the length of the data to add
Returns

None

Remarks

This function is aliased to MD5AddData on non-PIC18 platforms.

Stack API > Hashes > Stack Members > MD5AddROMData Function


SHA1AddROMData Function

Contents | Index | Home
Previous | Up | Next
SHA1AddROMData Function
C
void SHA1AddROMData(
    HASH_SUM* theSum,
    ROM BYTE* data,
    WORD len
);
Description

Adds data to a SHA-1 hash calculation.

Preconditions

The hash context has already been initialized.

Parameters
Parameters | Description
theSum | a pointer to the hash context structure
data | the data to add to the hash
len | the length of the data to add
Returns

None

Remarks

This function is aliased to SHA1AddData on non-PIC18 platforms.

Stack API > Hashes > Stack Members > SHA1AddROMData Function


SHA1AddData Function

Contents | Index | Home
Previous | Up | Next
SHA1AddData Function
C
void SHA1AddData(
    HASH_SUM* theSum,
    BYTE* data,
    WORD len
);
Description

Adds data to a SHA-1 hash calculation.

Preconditions

The hash context has already been initialized.

Parameters
Parameters | Description
theSum | a pointer to the hash context structure
data | the data to add to the hash
len | the length of the data to add
Returns

None

Stack API > Hashes > Stack Members > SHA1AddData Function


MD5AddData Function

Contents | Index | Home
Previous | Up | Next
MD5AddData Function
C
void MD5AddData(
    HASH_SUM* theSum,
    BYTE* data,
    WORD len
);
Description

Adds data to an MD5 hash calculation.

Preconditions

The hash context has already been initialized.

Parameters
Parameters | Description
theSum | a pointer to the hash context structure
data | the data to add to the hash
len | the length of the data to add
Returns

None

Stack API > Hashes > Stack Members > MD5AddData Function


Hashes Internal Members

Contents | Index | Home
Previous | Up | Next
Hashes Internal Members

The following functions and variables are designated as internal to the Hashes module.

Enumerations
Name | Description
HASH_TYPE | Type of hash being calculated
Functions
Name | Description
SHA1HashBlock | Calculates the SHA-1 hash sum of a block.
MD5HashBlock | Calculates the MD5 hash sum of a block.
Module

Hashes

Variables
Name | Description
_MD5_k | Array of pre-defined K values for MD5
_MD5_r | Array of pre-defined R vales for MD5
lastBlock | Stores a copy of the last block with the required padding
Stack API > Hashes > Internal Members


_MD5_k Variable

Contents | Index | Home
Previous | Up | Next
_MD5_k Variable
C
ROM DWORD _MD5_k[64] = { 0xD76AA478, 0xE8C7B756, 0x242070DB, 0xC1BDCEEE, 0xF57C0FAF, 0x4787C62A, 0xA8304613, 0xFD469501, 0x698098D8, 0x8B44F7AF, 0xFFFF5BB1, 0x895CD7BE, 0x6B901122, 0xFD987193, 0xA679438E, 0x49B40821, 0xF61E2562, 0xC040B340, 0x265E5A51, 0xE9B6C7AA, 0xD62F105D, 0x02441453, 0xD8A1E681, 0xE7D3FBC8, 0x21E1CDE6, 0xC33707D6, 0xF4D50D87, 0x455A14ED, 0xA9E3E905, 0xFCEFA3F8, 0x676F02D9, 0x8D2A4C8A, 0xFFFA3942, 0x8771F681, 0x6D9D6122, 0xFDE5380C, 0xA4BEEA44, 0x4BDECFA9, 0xF6BB4B60, 0xBEBFBC70, 0x289B7EC6, 0xEAA127FA, 0xD4EF3085, 0x04881D05, 0xD9D4D039, 0xE6DB99E5, 0x1FA27CF8, 0xC4AC5665, 0xF4292244, 0x432AFF97, 0xAB9423A7, 0xFC93A039, 0x655B59C3, 0x8F0CCC92, 0xFFEFF47D, 0x85845DD1, 0x6FA87E4F, 0xFE2CE6E0, 0xA3014314, 0x4E0811A1, 0xF7537E82, 0xBD3AF235, 0x2AD7D2BB, 0xEB86D391 };
Description

Array of pre-defined K values for MD5

Stack API > Hashes > Internal Members > _MD5_k Variable


_MD5_r Variable

Contents | Index | Home
Previous | Up | Next
_MD5_r Variable
C
ROM BYTE _MD5_r[64] = {7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21};
Description

Array of pre-defined R vales for MD5

Stack API > Hashes > Internal Members > _MD5_r Variable


lastBlock Variable

Contents | Index | Home
Previous | Up | Next
lastBlock Variable
C
BYTE lastBlock[64];
Description

Stores a copy of the last block with the required padding

Stack API > Hashes > Internal Members > lastBlock Variable


HASH_TYPE Enumeration

Contents | Index | Home
Previous | Up | Next
HASH_TYPE Enumeration
C
typedef enum {
  HASH_MD5 = 0u,
  HASH_SHA1
} HASH_TYPE;
Description

Type of hash being calculated

Members
Members | Description
HASH_MD5 = 0u | MD5 is being calculated
HASH_SHA1 | SHA-1 is being calculated
Stack API > Hashes > Internal Members > HASH_TYPE Enumeration


SHA1HashBlock Function

Contents | Index | Home
Previous | Up | Next
SHA1HashBlock Function
C
static void SHA1HashBlock(
    BYTE* data,
    DWORD* h0,
    DWORD* h1,
    DWORD* h2,
    DWORD* h3,
    DWORD* h4
);
Description

This function calculates the SHA-1 hash sum over a block and updates the values of h0-h3 with the next context.

Preconditions

The data pointer must be WORD aligned on 16-bit parts and DWORD aligned on 32-bit PICs. If alignment is not correct, a memory alignment exception will occur.

Parameters
Parameters | Description
data | The block of 64 bytes to hash
h0 | the current hash context h0 value
h1 | the current hash context h1 value
h2 | the current hash context h2 value
h3 | the current hash context h3 value
h4 | the current hash context h4 value
Returns

None

Stack API > Hashes > Internal Members > SHA1HashBlock Function


MD5HashBlock Function

Contents | Index | Home
Previous | Up | Next
MD5HashBlock Function
C
static void MD5HashBlock(
    BYTE* data,
    DWORD* h0,
    DWORD* h1,
    DWORD* h2,
    DWORD* h3
);
Description

This function calculates the MD5 hash sum over a block and updates the values of h0-h3 with the next context.

Preconditions

The data pointer must be WORD aligned on 16-bit parts and DWORD aligned on 32-bit PICs. If alignment is not correct, a memory alignment exception will occur.

Parameters
Parameters | Description
data | The block of 64 bytes to hash
h0 | the current hash context h0 value
h1 | the current hash context h1 value
h2 | the current hash context h2 value
h3 | the current hash context h3 value
Returns

None

Stack API > Hashes > Internal Members > MD5HashBlock Function


Helpers

Contents | Index | Home
Previous | Up | Next
Helpers
Functions | Variables

This module contains several helper functions used throughout the TCP/IP Stack. Some of these duplicate functionality already implemented in the compiler's default libraries. In those cases, the compiler's version is used and the stack's version is omitted.

Topics
Name | Description
Helpers Public Members | Functions and variables accessible by the stack application
Functions | The following table lists functions in this documentation.
Variables | The following table lists variables in this documentation.
Functions
Name | Description
LFSRRand | Returns a pseudo-random 16-bit unsigned integer in the range from 0 to 65535 (0x0000 to 0xFFFF).
LFSRSeedRand | Seeds the LFSR random number generator invoked by the LFSRRand() function. The prior seed is returned.
Variables
Name | Description
dwLFSRRandSeed | Default Random Number Generator seed. 0x41FE9F9E corresponds to calling LFSRSeedRand(1)
Stack API > Helpers


Helpers Public Members

Contents | Index | Home
Previous | Up | Next
Helpers Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
Base64Decode | Decodes a Base-64 array to its literal representation.
Base64Encode | Encodes a binary array to Base-64.
btohexa_high | Converts the upper nibble of a binary value to a hexadecimal ASCII byte.
btohexa_low | Converts the lower nibble of a binary value to a hexadecimal ASCII byte.
CalcIPBufferChecksum | Calculates an IP checksum in the MAC buffer itself.
CalcIPChecksum | Calculates an IP checksum value.
ExtractURLFields | Extracts all parameters from an URL string (ex: "http://admin:passwd@www.microchip.com:8080/myfile.gif" is split into {PROTOCOL_HTTP, "admin", "passwd", "www.microchip.com", 8080, "/myfile.gif"}.
FormatNetBIOSName | Formats a string to a valid NetBIOS name.
GenerateRandomDWORD | Generates a random DWORD.
hexatob | Converts a hex string to a single byte.
leftRotateDWORD | Left-rotates a DWORD.
Replace | Replaces all instances of a particular substring with a new string
ROMStringToIPAddress | Converts a string to an IP address
stricmppgm2ram | Case-insensitive comparison of a string in RAM to a string in ROM.
StringToIPAddress | Converts a string to an IP address
strupr | Converts a string to uppercase.
strnchr | Searches a string up to a specified number of characters for a specific character.
swapl | Swaps the endian-ness of a DWORD.
swaps | Swaps the endian-ness of a WORD.
uitoa | Converts an unsigned integer to a decimal string.
ultoa | Converts an unsigned integer to a decimal string.
UnencodeURL | Decodes a URL-encoded string.
Macros
Name | Description
leftRotateDWORD | Rotations are more efficient in C30 and C32
ROMStringToIPAddress | Non-ROM variant for C30 and C32
Module

Helpers

Stack API > Helpers > Public Members


Base64Decode Function

Contents | Index | Home
Previous | Up | Next
Base64Decode Function
C
WORD Base64Decode(
    BYTE* cSourceData,
    WORD wSourceLen,
    BYTE* cDestData,
    WORD wDestLen
);
Description

Decodes a Base-64 array to its literal representation.

Preconditions

None

Parameters
Parameters | Description
cSourceData | Pointer to a string of Base-64 encoded data
wSourceLen | Length of the Base-64 source data Maximum length that can be written to cDestData
cDestData | Pointer to write the decoded data
Returns

Number of decoded bytes written to cDestData.

Remarks

This function is binary safe and will ignore invalid characters (CR, LF, etc). If cSourceData is equal to cDestData, the data will be converted in-place. If cSourceData is not equal to cDestData, but the regions overlap, the behavior is undefined.

Decoded data is always at least 1/4 smaller than the source data.

Stack API > Helpers > Public Members > Base64Decode Function


Base64Encode Function

Contents | Index | Home
Previous | Up | Next
Base64Encode Function
C
WORD Base64Encode(
    BYTE* cSourceData,
    WORD wSourceLen,
    BYTE* cDestData,
    WORD wDestLen
);
Description

Encodes a binary array to Base-64.

Preconditions

None

Parameters
Parameters | Description
cSourceData | Pointer to a string of binary data
wSourceLen | Length of the binary source data Maximum length that can be written to cDestData
cDestData | Pointer to write the Base-64 encoded data
Returns

Number of encoded bytes written to cDestData. This will always be a multiple of 4.

Remarks

Encoding cannot be performed in-place. If cSourceData overlaps with cDestData, the behavior is undefined.

Encoded data is always at least 1/3 larger than the source data. It may be 1 or 2 bytes larger than that.

Stack API > Helpers > Public Members > Base64Encode Function


btohexa_high Function

Contents | Index | Home
Previous | Up | Next
btohexa_high Function
C
BYTE btohexa_high(
    BYTE b
);
Description

Converts the upper nibble of a binary value to a hexadecimal ASCII byte. For example, btohexa_high(0xAE) will return 'A'.

Preconditions

None

Parameters
Parameters | Description
b | the byte to convert
Returns

The upper hexadecimal ASCII byte '0'-'9' or 'A'-'F'.

Stack API > Helpers > Public Members > btohexa_high Function


btohexa_low Function

Contents | Index | Home
Previous | Up | Next
btohexa_low Function
C
BYTE btohexa_low(
    BYTE b
);
Description

Converts the lower nibble of a binary value to a hexadecimal ASCII byte. For example, btohexa_high(0xAE) will return 'E'.

Preconditions

None

Parameters
Parameters | Description
b | the byte to convert
Returns

The lower hexadecimal ASCII byte '0'-'9' or 'A'-'F'.

Stack API > Helpers > Public Members > btohexa_low Function


CalcIPBufferChecksum Function

Contents | Index | Home
Previous | Up | Next
CalcIPBufferChecksum Function
C
WORD CalcIPBufferChecksum(
    WORD len
);
Description

This function calculates an IP checksum over an array of input data existing in the MAC buffer. The checksum is the 16-bit one's complement of one's complement sum of all words in the data (with zero-padding if an odd number of bytes are summed). This checksum is defined in RFC 793.

Preconditions

TCP is initialized and the MAC buffer pointer is set to the start of the buffer.

Parameters
Parameters | Description
len | number of bytes to be checksummed
Returns

The calculated checksum.

Remarks

All Microchip MACs should perform this function in hardware.

Stack API > Helpers > Public Members > CalcIPBufferChecksum Function


CalcIPChecksum Function

Contents | Index | Home
Previous | Up | Next
CalcIPChecksum Function
C
WORD CalcIPChecksum(
    BYTE* buffer,
    WORD len
);
Description

This function calculates an IP checksum over an array of input data. The checksum is the 16-bit one's complement of one's complement sum of all words in the data (with zero-padding if an odd number of bytes are summed). This checksum is defined in RFC 793.

Preconditions

buffer is WORD aligned (even memory address) on 16- and 32-bit PICs.

Parameters
Parameters | Description
buffer | pointer to the data to be checksummed
count | number of bytes to be checksummed
Returns

The calculated checksum.

Stack API > Helpers > Public Members > CalcIPChecksum Function


ExtractURLFields Function

Contents | Index | Home
Previous | Up | Next
ExtractURLFields Function
C
BYTE ExtractURLFields(
    BYTE * vURL,
    PROTOCOLS * protocol,
    BYTE * vUsername,
    WORD * wUsernameLen,
    BYTE * vPassword,
    WORD * wPasswordLen,
    BYTE * vHostname,
    WORD * wHostnameLen,
    WORD * wPort,
    BYTE * vFilePath,
    WORD * wFilePathLen
);
Description

Extracts all parameters from an URL string (ex: "http://admin:passwd@www.microchip.com:8080/myfile.gif" is split into {PROTOCOL_HTTP, "admin", "passwd", "www.microchip.com", 8080, "/myfile.gif"}.

The URL string can be null terminated, or alternatively could be terminated by a carriage return or line feed.

If the protocol is unrecognized or the protocol is recognized but the URL is malformed, than an error is safely returned. For more information on URL/URI interpretation see RFC 2396.

Preconditions

This function is commented out by default to save code space because it is not used by any current stack features. However, if you want to use it, go ahead and uncomment it. It has been tested, so it (should) work correctly.

Parameters
Parameters | Description
vURL | Pointer to null terminated URL to decode and extract from. This parameter is required and needs to have the minimum RFC 1738 components in it (protocol and hostname).
protocol | Optional pointer to a PROTOCOLS enum to retrieve the decoded protocol type. If this parameter is unneeded, specify a NULL pointer. The protocol is a required part of the URL, so it must always be present. The protocol also determines what scheme all other parameters are decoded using, so the function will fail if an unrecognized protocol is provided. The PROTOCOLS enum members show all of the currently supported protocols for this function. For the example URL provided in the function description, PROTOCOL_HTTP would be returned for this field.
vUsername | Optional pointer to a buffer to write the decoded username portion of the URL. If the URL does not contain a username or a NULL pointer is supplied, then this field is ignored. For the example URL provided in the function description, "admin" would be returned for this field.
wUsernameLen | On call: Optional pointer to a WORD specifying the maximum length of the vUsername buffer, including the null terminator character. Upon return: If wUsernameLen and vUsername are non-NULL, the *wUsernameLen WORD is updated with the actual number of characters written to the vUsername buffer, including the null terminator character. If vUsername is NULL but wUsernameLen is non-NULL, then no characters are copied, but *wUsernameLen will return the number of characters required to fit the full username string. If wUsernameLen is NULL, then the username field in the URL, if present, is ignored and the vUsername pointer is not used. If zero characters were written, this indicates that the URL did not contain a username field. If one character was written, this indicates that a username field was present, but was a zero character string (ex: ""). For the example URL provided in the function description, 6 (0x0006) would be returned for this field.
vPassword | Optional pointer to a buffer to write the decoded password portion of the URL. If the URL does not contain a password or a NULL pointer is supplied, then this field is ignored. For the example URL provided in the function description, "passwd" would be returned for this field.
wPasswordLen | On call: Optional pointer to a WORD specifying the maximum length of the vPassword buffer, including the null terminator character. Upon return: If wPasswordLen and vPassword are non-NULL, the *wPasswordLen WORD is updated with the actual number of characters written to the vPassword buffer, including the null terminator character. If vPassword is NULL but wPasswordLen is non-NULL, then no characters are copied, but *wPasswordLen will return the number of characters required to fit the full password string. If wPasswordLen is NULL, then the password field in the URL, if present, is ignored and the vPassword pointer is not used. If zero characters were written, this indicates that the URL did not contain a password field. If one character was written, this indicates that a password field was present, but was a zero character string (ex: ""). For the example URL provided in the function description, 7 (0x0007) would be returned for this field.
vHostname | Optional pointer to a buffer to write the decoded hostname portion of the URL. All Internet URLs must contain a hostname or IP address, however, if a NULL pointer is supplied, then this field is ignored. For the example URL provided in the function description, "www.microchip.com" would be returned for this field. If the URL was "http://192.168.0.1", then this field would be returned as "192.168.0.1". The IP address would not be decoded to a DWORD (use the StringToIPAddress() helper function to do this).
wHostnameLen | On call: Optional pointer to a WORD specifying the maximum length of the vHostname buffer, including the null terminator character. Upon return: If wHostnameLen and vHostname are non-NULL, the *wHostnameLen WORD is updated with the actual number of characters written to the vHostname buffer, including the null terminator character. If vHostname is NULL but wHostnameLen is non-NULL, then no characters are copied, but *wHostnameLen will return the number of characters required to fit the full hostname string. If wHostnameLen is NULL, then the hostname field in the URL, is ignored and the vHostname pointer is not used. For the example URL provided in the function description, 18 (0x0012) would be returned for this field. If the URL was "http://192.168.0.1", then this field would be returned as 12 (0x000C).
wPort | Optional pointer to a WORD specifying the TCP or UDP port that the server is listening on. If the port field is absent from the URL, then this parameter will specify the default port for the protocol. For example, "http://www.microchip.com" would result in 80 being return as the specified port. If the wPort pointer is NULL, then the port field in the URL is ignored, if present.
vFilePath | Optional pointer to a buffer to write the decoded file path portion of the URL. If a NULL pointer is supplied, then this field is ignored. If a file path is not present in the URL, then "/" will be returned in this field. For the example URL provided in the function description, "/myfile.gif" would be returned for this field.
wFilePathLen | On call: Optional pointer to a WORD specifying the maximum length of the vFilePath buffer, including the null terminator character. Upon return: If wFilePathLen and vFilePath are non-NULL, the *wFilePathLen WORD is updated with the actual number of characters written to the vFilePath buffer, including the null terminator character. If vFilePath is NULL but wFilePathLen is non-NULL, then no characters are copied, but *wFilePathLen will return the number of characters required to fit the full file path string. If wFilePathLen is NULL, then the file path field in the URL, if present, is ignored and the vFilePath pointer is not used. This function always returns "/" if no file path is present, so *wFilePathLen will also be at least 2 characters ('/' and null terminator) if the pointer is non-NULL. For the example URL provided in the function description, 12 (0x000C) would be returned for this field.
Returns

Zero on success. Nonzero indicates an error code. If a nonzero error code is returned, none of the returned buffers or pointer values should be treated as valid, but some of them may have been written to. The following are all possible return values.

0 | No error
1 | Protocol unknown (additional code needs to be added to ExtractURLFields() and the PROTOCOLS enum needs to be updated if you want to decode URLs of this protocol type.
2 | URL malformed. Illegal or unknown URL format encountered.
3 | Buffer too small. One of the input buffer sizes is too small to contain the URL parameter.
Stack API > Helpers > Public Members > ExtractURLFields Function


FormatNetBIOSName Function

Contents | Index | Home
Previous | Up | Next
FormatNetBIOSName Function
C
void FormatNetBIOSName(
    BYTE Name[16]
);
Description

This function formats a string to a valid NetBIOS name. Names will be exactly 16 characters, as defined by the NetBIOS spec. The 16th character will be a 0x00 byte, while the other 15 will be the provided string, padded with spaces as necessary.

Preconditions

None

Parameters
Parameters | Description
Name | the string to format as a NetBIOS name. This parameter must have at least 16 bytes allocated.
Returns

None

Stack API > Helpers > Public Members > FormatNetBIOSName Function


GenerateRandomDWORD Function

Contents | Index | Home
Previous | Up | Next
GenerateRandomDWORD Function
C
DWORD GenerateRandomDWORD();
Description

This function generates a random 32-bit integer. It collects randomness by comparing the A/D converter's internal R/C oscillator clock with our main system clock. By passing collected entropy to the LFSRSeedRand()/LFSRRand() functions, the output is normalized (deskewed) in the hopes of meeting statistical randomness tests.

Preconditions

None

Returns

Random 32-bit number.

Side Effects

This function uses the A/D converter (and so you must disable interrupts if you use the A/D converted in your ISR). The LFSRRand() function will be reseeded, and Timer0 (PIC18) and Timer1 (PIC24, dsPIC, and PIC32) will be used. TMR#H:TMR#L will have a new value. Note that this is the same timer used by the Tick module.

Remarks

This function times out after 1 second of attempting to generate the random DWORD. In such a case, the output may not be truly random. Typically, this function executes in around 500,000 instruction cycles.

The intent of this function is to produce statistically random and cryptographically secure random number. Whether or not this is true on all (or any) devices/voltages/temperatures is not tested.

Stack API > Helpers > Public Members > GenerateRandomDWORD Function


hexatob Function

Contents | Index | Home
Previous | Up | Next
hexatob Function
C
BYTE hexatob(
    WORD_VAL AsciiChars
);
Description

Converts a two-character ASCII hex string to a single packed byte.

Preconditions

None

Parameters
Parameters | Description
AsciiChars | WORD_VAL where .v[0] is the ASCII value for the lower nibble and .v[1] is the ASCII value for the upper nibble. Each must range from '0'-'9', 'A'-'F', or 'a'-'f'.
Returns

Resulting packed byte 0x00 - 0xFF.

Stack API > Helpers > Public Members > hexatob Function


leftRotateDWORD Function

Contents | Index | Home
Previous | Up | Next
leftRotateDWORD Function
C
DWORD leftRotateDWORD(
    DWORD val,
    BYTE bits
);
Description

This function rotates the bits in a 32-bit DWORD left by a specific number of bits.

Preconditions

None

Parameters
Parameters | Description
val | the DWORD to be rotated
bits | the number of bits by which to shift
Returns

Rotated DWORD value.

Remarks

This function is only implemented on 8-bit platforms for now. The 8-bit compilers generate excessive code for this function, while C30 and C32 already generate compact code. Those compilers are served by a macro defined in Helpers.h.

Stack API > Helpers > Public Members > leftRotateDWORD Function


leftRotateDWORD Macro

Contents | Index | Home
Previous | Up | Next
leftRotateDWORD Macro
C
#define leftRotateDWORD(x, n) (((x) << (n)) | ((x) >> (32-(n))))
Description

Rotations are more efficient in C30 and C32

Stack API > Helpers > Public Members > leftRotateDWORD Macro


Replace Function

Contents | Index | Home
Previous | Up | Next
Replace Function
C
SHORT Replace(
    BYTE * vExpression,
    ROM BYTE * vFind,
    ROM BYTE * vReplacement,
    WORD wMaxLen,
    BOOL bSearchCaseInsensitive
);
Description

Searches a string (vExpression) and replaces all instances of a particular substring (vFind) with a new string (vReplacement). The start offset to being searching and a maximum number of replacements can be specified. The search can be performed in a case sensitive or case insensitive manner.

Preconditions

This function is commented out by default to save code space because it is not used by any current stack features. However, if you want to use it, go ahead and uncomment it. It has been tested, so it (should) work correctly.

Parameters
Parameters | Description
vExpression | Null terminated string to search and make replacements within.
vFind | Null terminated string to search for.
vReplacement | Null terminated string to replace all instances of vFind with.
wMaxLen | Maximum length of the output vExpression string if string expansion is going to occur (replacement length is longer than find length). If the replacements will cause this maximum string length to be exceeded, then no replacements will be made and a negative result will be returned, indicating failure. If the replacement length is shorter or equal to the search length, then this parameter is ignored.
bSearchCaseInsensitive | Boolean indicating if the search should be performed in a case insensitive manner. Specify TRUE for case insensitive searches (slower) or FALSE for case sensitive searching (faster).
Returns

If zero or greater, indicates the count of how many replacements were made. If less than zero (negative result), indicates that wMaxLen was too small to make the necessary replacements. In this case, no replacements were made.

Remarks

If the replacement string length is shorter than or equal to the search string length and the search string occurs in multiple overlapping locations (ex: expression is "aaa", find is "aa", and replacement is "bb") then the first find match occuring when searching from left to right will be replaced. (ex: output expression will be "bba").

However, if the replacement string length is longer than the search string length, the search will occur starting from the end of the string and proceed to the beginning (right to left searching). In this case if the expression was "aaa", find was "aa", and replacement was "bbb", then the final output expression will be "abbb".

Stack API > Helpers > Public Members > Replace Function


ROMStringToIPAddress Function

Contents | Index | Home
Previous | Up | Next
ROMStringToIPAddress Function
C
BOOL ROMStringToIPAddress(
    ROM BYTE* str,
    IP_ADDR* IPAddress
);
Description

This function parses a dotted-quad decimal IP address string into an IP_ADDR struct. The output result is big-endian.

Preconditions

None

Parameters
Parameters | Description
str | Pointer to a dotted-quad IP address string
IPAddress | Pointer to IP_ADDR in which to store the result
Return Values
Return Values | Description
TRUE | an IP address was successfully decoded
FALSE | no IP address could be found, or the format was incorrect
Remarks

This function is aliased to StringToIPAddress on non-PIC18 platforms.

Stack API > Helpers > Public Members > ROMStringToIPAddress Function


ROMStringToIPAddress Macro

Contents | Index | Home
Previous | Up | Next
ROMStringToIPAddress Macro
C
#define ROMStringToIPAddress(a,b) StringToIPAddress((BYTE*)a,b)
Description

Non-ROM variant for C30 and C32

Stack API > Helpers > Public Members > ROMStringToIPAddress Macro


stricmppgm2ram Function

Contents | Index | Home
Previous | Up | Next
stricmppgm2ram Function
C
signed char stricmppgm2ram(
    BYTE* a,
    ROM BYTE* b
);
Description

Performs a case-insensitive comparison of a string in RAM to a string in ROM. This function performs identically to strcmppgm2ram, except that the comparison is not case-sensitive.

Preconditions

None

Parameters
Parameters | Description
a | Pinter to tring in RAM
b | Pointer to string in ROM
Return Values
Return Values | Description
-1 | a < b
0 | a = b
1 | a > b
Stack API > Helpers > Public Members > stricmppgm2ram Function


StringToIPAddress Function

Contents | Index | Home
Previous | Up | Next
StringToIPAddress Function
C
BOOL StringToIPAddress(
    BYTE* str,
    IP_ADDR* IPAddress
);
Description

This function parses a dotted-quad decimal IP address string into an IP_ADDR struct. The output result is big-endian.

Preconditions

None

Parameters
Parameters | Description
str | Pointer to a dotted-quad IP address string
IPAddress | Pointer to IP_ADDR in which to store the result
Return Values
Return Values | Description
TRUE | an IP address was successfully decoded
FALSE | no IP address could be found, or the format was incorrect
Stack API > Helpers > Public Members > StringToIPAddress Function


strupr Function

Contents | Index | Home
Previous | Up | Next
strupr Function
C
char * strupr(
    char* s
);
Description

This function converts strings to uppercase on platforms that do not already have this function defined. All lower-case characters are converted, an characters not included in 'a'-'z' are left as-is.

Preconditions

None

Parameters
Parameters | Description
s | the null-terminated string to be converted.
Returns

Pointer to the initial string.

Stack API > Helpers > Public Members > strupr Function


strnchr Function

Contents | Index | Home
Previous | Up | Next
strnchr Function
C
char * strnchr(
    const char * searchString,
    size_t count,
    char c
);
Description

Searches a string up to a specified number of characters for a specific character. The string is searched forward and the first occurance location is returned. If the search character is not present in the string, or if the maximum character count is reached first, then a NULL pointer is returned.

Preconditions

None

Parameters
Parameters | Description
searchString | Pointer to a null terminated string to search. If count is less than the string size, then the string need not be null terminated.
count | Maximum number of characters to search before aborting.
c | Character to search for
Returns

Pointer to the first occurance of the character c in the string searchString. If the character is not found or the maximum count is reached, a NULL pointer is returned.

Stack API > Helpers > Public Members > strnchr Function


swapl Function

Contents | Index | Home
Previous | Up | Next
swapl Function
C
DWORD swapl(
    DWORD v
);
Description

Swaps the endian-ness of a DWORD.

Preconditions

None

Parameters
Parameters | Description
v | the DWORD to swap
Returns

The swapped version of v.

Stack API > Helpers > Public Members > swapl Function


swaps Function

Contents | Index | Home
Previous | Up | Next
swaps Function
C
WORD swaps(
    WORD v
);
Description

Swaps the endian-ness of a WORD.

Preconditions

None

Parameters
Parameters | Description
v | the WORD to swap
Returns

The swapped version of v.

Stack API > Helpers > Public Members > swaps Function


uitoa Function

Contents | Index | Home
Previous | Up | Next
uitoa Function
C
void uitoa(
    WORD Value,
    BYTE* Buffer
);
Description

Converts a 16-bit unsigned integer to a null-terminated decimal string.

Preconditions

None

Parameters
Parameters | Description
Value | The number to be converted
Buffer | Pointer in which to store the converted string
Returns

None

Stack API > Helpers > Public Members > uitoa Function


ultoa Function

Contents | Index | Home
Previous | Up | Next
ultoa Function
C
void ultoa(
    DWORD Value,
    BYTE* Buffer
);
Description

C32 < 1.12 and C30 < v3.25 need this 2 parameter stack implemented function

Converts a 32-bit unsigned integer to a null-terminated decimal string.

Preconditions

None

Parameters
Parameters | Description
Value | The number to be converted
Buffer | Pointer in which to store the converted string
Returns

None

************************************************************************

HI-TECH PICC-18 PRO 9.63, C30 v3.25, and C32 v1.12 already have a ultoa() library function C18 already has a ultoa() function that more-or-less matches this one C32 < 1.12 and C30 < v3.25 need this function

Stack API > Helpers > Public Members > ultoa Function


UnencodeURL Function

Contents | Index | Home
Previous | Up | Next
UnencodeURL Function
C
void UnencodeURL(
    BYTE* URL
);
Description

This function is deprecated except for use with HTTP Classic. It attempts to decode a URL encoded string, converting all hex escape sequences into a literal byte. However, it is inefficient over long strings and does not handle URL-encoded data strings ('&' and '=').

Preconditions

None

Parameters
Parameters | Description
URL | the null-terminated string to decode
Returns

None

Stack API > Helpers > Public Members > UnencodeURL Function


Functions

Contents | Index | Home
Previous | Up | Next
Functions
Functions
Name | Description
LFSRRand | Returns a pseudo-random 16-bit unsigned integer in the range from 0 to 65535 (0x0000 to 0xFFFF).
LFSRSeedRand | Seeds the LFSR random number generator invoked by the LFSRRand() function. The prior seed is returned.
Module

Helpers

Stack API > Helpers > Functions


LFSRRand Function

Contents | Index | Home
Previous | Up | Next
LFSRRand Function
C
WORD LFSRRand();
Description

Returns a pseudo-random 16-bit unsigned integer in the range from 0 to 65535 (0x0000 to 0xFFFF). The random number is generated using a Linear Feedback Shift Register (LFSR) type pseudo-random number generator algorithm. The LFSR can be seeded by calling the LFSRSeedRand() function to generate the same sequence of random numbers as a prior string of calls.

The internal LFSR will repeat after 2^32-1 iterations.

Preconditions

None

Returns

Random 16-bit unsigned integer.

Side Effects

The internal LFSR seed is updated so that the next call to LFSRRand() will return a different random number.

Remarks

None

Stack API > Helpers > Functions > LFSRRand Function


LFSRSeedRand Function

Contents | Index | Home
Previous | Up | Next
LFSRSeedRand Function
C
DWORD LFSRSeedRand(
    DWORD dwSeed
);
Description

Seeds the LFSR random number generator invoked by the LFSRRand() function. The prior seed is returned.

Preconditions

None

Parameters
Parameters | Description
wSeed | The new 32-bit seed value to assign to the LFSR.
Returns

The last seed in use. This can be saved and restored by a subsequent call to LFSRSeedRand() if you wish to use LFSRRand() in multiple contexts without disrupting the random number sequence from the alternative context. For example, if App 1 needs a given sequence of random numbers to perform a test, if you save and restore the seed in App 2, it is possible for App 2 to not disrupt the random number sequence provided to App 1, even if the number of times App 2 calls LFSRRand() varies.

Side Effects

None

Remarks

Upon initial power up, the internal seed is initialized to 0x1. Using a dwSeed value of 0x0 will return the same sequence of random numbers as using the seed of 0x1.

Stack API > Helpers > Functions > LFSRSeedRand Function


Variables

Contents | Index | Home
Previous | Up | Next
Variables
Module

Helpers

Variables
Name | Description
dwLFSRRandSeed | Default Random Number Generator seed. 0x41FE9F9E corresponds to calling LFSRSeedRand(1)
Stack API > Helpers > Variables


dwLFSRRandSeed Variable

Contents | Index | Home
Previous | Up | Next
dwLFSRRandSeed Variable
C
DWORD dwLFSRRandSeed = 0x41FE9F9E;
Description

Default Random Number Generator seed. 0x41FE9F9E corresponds to calling LFSRSeedRand(1)

Stack API > Helpers > Variables > dwLFSRRandSeed Variable


HTTP2 Server

Contents | Index | Home
Previous | Up | Next
HTTP2 Server

The HTTP2 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.

Three main components are necessary to understand how the HTTP2 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.

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 is being stored in Flash program memory, the MPFS2 Utility will generate a C source file image to be included in the project.

When dynamic variables are added or removed from your application, the MPFS2 Utility will update HTTPPrint.h. When this happens, the project must be recompiled in the MPLAB IDE to ensure that all the new variable indices get added into the application.

CustomHTTPApp.c

This file implements the web application. It describes the output for dynamic variables (via HTTPPrint_varname callbacks), parses data submitted through forms (in HTTPExecuteGet and HTTPExecutePost) and validates authorization credentials (in HTTPAuthenticate). The exact functionality of these callbacks is described within the demo application's web pages, and is also documented within the CustomHTTPApp.c example that is distributed with the stack.

HTTPPrint.h

This file is generated automatically by the MPFS2 Utility. It indexes all the dynamic variables and provides the "glue" between the variables located in the web pages and their associated HTTPPrint_varname callback functions defined in CustomHTTPApp.c. This file does not require modification by the programmer.

Topics
Name | Description
HTTP2 Features | Features available in the HTTP2 module
HTTP2 Public Members | Functions and variables accessible or implemented by the stack application
HTTP2 Stack Members | Functions and variables intended to be accessed only by the stack
HTTP2 Internal Members | Functions and variables used internally by the HTTP2 module
Stack API > HTTP2 Server


HTTP2 Features

Contents | Index | Home
Previous | Up | Next
HTTP2 Features

The HTTP2 web server module has many capabilities. The following topics will introduce these features and provide examples.

Module

HTTP2 Server

Topics
Name | Description
HTTP2 Dynamic Variables | Displays real-time data in web pages or other outputs
HTTP2 Form Processing | Allows client input from HTML forms
HTTP2 Authentication | Verifies user names and passwords for access
HTTP2 Cookies | Allows cookies to be set/retrieved, adding state to the HTTP protocol
HTTP2 Compression | Compresses static files for faster throughput
Stack API > HTTP2 Server > Features


HTTP2 Dynamic Variables

Contents | Index | Home
Previous | Up | Next
HTTP2 Dynamic Variables

One of the most basic needs is to provide status information back to the user of your web application. The HTTP server provides for this using dynamic variable substitution callbacks. These commands in your HTML code will alert the server to execute a callback function at that point, which the developer creates to write data into the web page. Dynamic Variables should be considered the output of your application.

Basic Use

To create a dynamic variable, simply enclose the name of the variable inside a pair of tilde (~) characters within the web pages' HTML source code. (ex: ~myVariable~) When you run the MPFS2 Utility to generate the web pages, it will automatically index these variables in HTTPPrint.h. This index will instruct your application to invoke the function HTTPPrint_myVariable when this string is encountered.

Here is an example of using a dynamic variable to insert the build date of your application into the web pages:

Copy Code
<div class="examplebox code">~builddate~</div>

The associated callback will print the value into the web page:

Copy Code
void HTTPPrint_builddate(void)
{
    TCPPutROMString(sktHTTP,(ROM void*)__DATE__);
}
Passing Parameters

You can also pass parameters to dynamic variables by placing numeric values inside of parenthesis after the variable name. For example, ~led(2)~ will print the value of the second LED. The numeric values are passed as WORD values to your callback function. You can pass as many parameters as you wish to these functions, and if your C code has constants defined, those will be parsed as well. (ex: ~pair(3,TRUE)~)

The following code inserts the value of the push buttons into the web page, all using the same callback function:

Copy Code
<div class="examplebox code">btn(3)~ btn(2)~ btn(1)~ btn(0)~</div>

This associated callback will print the value of the requested button to the web page:

Copy Code
void HTTPPrint_btn(WORD num)
{
    // Determine which button
    switch(num)
    {
        case 0:
            num = BUTTON0_IO;
            break;
        case 1:
            num = BUTTON1_IO;
            break;
        case 2:
            num = BUTTON2_IO;
            break;
        case 3:
            num = BUTTON3_IO;
            break;
        default:
            num = 0;
    }

    // Print the output
    if(num == 1)
        TCPPutROMString(sktHTTP, "up");
    else
        TCPPutROMString(sktHTTP, "down");
}
Longer Outputs

The HTTP protocol operates in a fixed memory buffer for transmission, so not all data can be sent at once. Care must be taken inside of your callback function to avoid overrunning this buffer.

The HTTP2 web server verifies that at least 16 bytes are free in this buffer before invoking a callback. For short outputs (less than 16 bytes), callbacks need only to call the appropriate TCPPut function and return. For longer outputs, callback functions must check how much space is available, write up to that many bytes, then return. The callback will be invoked again when more space is free.

To manage the output state, callbacks should make use of curHTTP.callbackPos. This DWORD value is set to zero when a callback is first invoked. If a callback is only writing part of its output, it should set this field to a non-zero value to indicate that it should be called again when more space is available. This value will be available to the callback during the next call, which allows the function to resume output where it left off. A common use is to store the number of bytes written, or remaining to be written, in this field. Once the callback is finished writing its output, it must set curHTTP.callbackPos back to zero in order to indicate completion.

As an example, this code outputs the current value of the LCD display, which is 32 bytes on many Microchip development boards:

Copy Code
<div class="examplebox code">~lcdtext~</div>

The following callback function handles the output, and manages its state for multiple calls:

Copy Code
void HTTPPrint_lcdtext(void)
{
    WORD len;

    // Determine how many bytes we can write
    len = TCPIsPutReady(sktHTTP);

    // If just starting, set callbackPos
    if(curHTTP.callbackPos == 0)
        curHTTP.callbackPos = 32;

    // Write a byte at a time while we still can
    // It may take up to 12 bytes to write a character
    // (spaces and newlines are longer)
    while(len > 12 && curHTTP.callbackPos)
    {
        // After 16 bytes write a newline
        if(curHTTP.callbackPos == 16)
            len -= TCPPutROMString(sktHTTP, (ROM BYTE*)"<br />");

        if(LCDText[32-curHTTP.callbackPos] == ' ' || LCDText[32-curHTTP.callbackPos] == '\0')
            len -= TCPPutROMString(sktHTTP, (ROM BYTE*)"&nbsp;");
        else
            len -= TCPPut(sktHTTP, LCDText[32-curHTTP.callbackPos]);

        curHTTP.callbackPos--;
    }
}

The initial call to TCPIsPutReady determines how many bytes can be written to the buffer right now. The TCPPut functions all return the number of bytes written, so we can subtract that value from len to track how much buffer space is left. When buffer space is exhausted, the function exits and waits to be called again. For subsequent calls, the value of curHTTP.callbackPos is exactly as we left it. The function resumes its output at that point.

Including Files

Often it is useful to include the entire contents of another file in your output. Most web pages have at least some portion that does not change, such as the header, menu of links, and footer. These sections can be abstracted out into separate files which makes them easier to manage and conserves storage space.

To include the entire contents of another file, use a dynamic variable that starts with "inc:", such as ~inc:header.inc~. This sequence will cause the file header.inc to be read from the file system and inserted at this location.

The following example indicates how to include a standard menu bar section into every page:

Copy Code
<div id="menu">~inc:menu.inc~</div>

At this time, dynamic variables are not recursive, so any variables located inside files included in this manner are not parsed.

Stack API > HTTP2 Server > Features > Dynamic Variables


HTTP2 Form Processing

Contents | Index | Home
Previous | Up | Next
HTTP2 Form Processing

Many applications need to accept data from a user. A common solution is to present a form to the user in a web page, then have the device process the values submitted via this form. Web forms are usually submitted using one of two methods (GET and POST), and the HTTP2 web server supports both.

The GET Method

The GET method appends the data to the end of the URI. This data follows the question mark (?) in the browser's address bar. (ex: http://mchpboard/form.htm?led1=0&led2=1&led3=0) Data sent via GET is automatically decoded and stored in the curHTTP.data array. Since it is to be stored in memory, this data is limited to the size of curHTTP.data, which by default is 100 bytes. However, it is generally easier to process data received in this manner.

The callback function HTTPExecuteGet is implemented by the application developer to process this data and perform any necessary actions. The functions HTTPGetArg and HTTPGetROMArg provide an easy method to retrieve submitted values for processing.

The following example demonstrates a form to control several LEDs.

Copy Code
<form method="get" action="leds.htm">
  LED 1: <input type="checkbox" name="led1" value="1" /><br />
  LED 2: <input type="checkbox" name="led2" value="1" /><br />
  LED 3: <input type="checkbox" name="led3" value="1" /><br />
  <input type="submit" value="Set LEDs" />
</form>

Suppose a user selects the checkboxes for LED 1 and LED3. The following string will be submitted to the server:

Copy Code
GET /leds.htm?led1=1&led3=1 HTTP/1.1

The HTTP2 web server will parse this request and store the following string in curHTTP.data:

Copy Code
"led1\01\0led3\01\0\0"

It will then call HTTPExecuteGet to process this input. To process this data, that callback needs to do several things. First, it should call MPFSGetFilename to verify which form was submitted. (This step may be omitted if only one form is provided by the application.) Next, since a checkbox control was used a default state of unchecked must be assumed. Finally, the callback should search for each argument it expects, compare the value, and set the LED pins accordingly. The following example satisfies all these requirements:

Copy Code
HTTP_IO_RESULT HTTPExecuteGet(void)
{
    BYTE *ptr, filename[20];

    // Load the file name (filename[] must be large enough to hold
    // the longest file name expected)
    MPFSGetFilename(curHTTP.file, filename, 20);

    // Verify the file name
    if(!strcmppgm2ram(filename, (ROM char*)"leds.htm"))
    {
        // Assume a default state of off
        LED1_IO = 0;
        LED2_IO = 0;
        LED3_IO = 0;

        // Search for each LED parameter and process
        ptr = HTTPGetROMArg(curHTTP.data, (ROM BYTE*)"led1");
        if(ptr)
            LED1_IO = (*ptr == '1');

        ptr = HTTPGetROMArg(curHTTP.data, (ROM BYTE*)"led2");
        if(ptr)
            LED2_IO = (*ptr == '1');

        ptr = HTTPGetROMArg(curHTTP.data, (ROM BYTE*)"led3");
        if(ptr)
            LED3_IO = (*ptr == '1');
    }

    // Indicate completion
    return HTTP_IO_DONE;
}
The POST Method

The POST method transmits data after all the request headers have been sent. This data is not visible in the browser's address bar, and can only be seen with a packet capture tool. It does however use the same URL encoding method.

The HTTP2 server does not perform any pre-parsing of this data. All POST data is left in the TCP buffer, so the custom application will need to access the TCP buffer directly to retrieve and decode it. The functions HTTPReadPostName and HTTPReadPostValue have been provided to assist with these requirements. However, these functions can only be used when at least entire variables are expected to fit in the TCP buffer at once.

Most POST processing functions will be implemented as state machines in order to use these functions. The variable curHTTP.smPost is available to store the current state. This state machine variable is reset to zero with each new request. Functions should generally implement a state to read a variable name, and another to read an expected value. Additional states may be helpful depending on the application.

The following example form accepts an e-mail address, a subject, and a message body. Since this data will likely total over 100 bytes, it should be submitted via POST.

Copy Code
<form method="post" action="/email.htm">
  To: <input type="text" name="to" maxlength="50" /><br />
  Subject: <input type="text" name="subject" maxlength="50" /><br />
  Message:<br />
  <textarea name="msg" rows="6"></textarea><br />
  <input type="submit" value="Send Message" /></div>
</form>

Suppose a user enters the following data into this form:

To: joe@picsaregood.com
Subject: Sent by a PIC
Message: I sent this message using my development board!

The HTTPExecutePost function will be called with the following data still in the TCP buffer:

Copy Code
to=joe%40picsaregood.com&subject=Sent+by+a+PIC
&msg=I+sent+this+message+using+my+development+board%21

To use the e-mail module, the application needs to read in the address and the subject, store those in RAM, then send the message. However, since the message is not guaranteed to fit in RAM all at once, it must be read as space is available and passed to the e-mail module. A state machine, coupled with the HTTPReadPostName and HTTPReadPostValue functions can simplify this greatly.

The following example callback function will properly parse this input. For this example, it is assumed that this is the only form the board accepts, so file name checking is not performed. The address will be stored at curHTTP.data[0:49], and the subject will be stored at curHTTP.data[50:99]. This is not the most optimal solution, but serves as a simple example.

Copy Code
HTTP_IO_RESULT HTTPExecutePost(void)
{
    BYTE *dest, temp[16];

    // Define state machine values
    #define SM_READ_NAME       (0u)
    #define SM_READ_VALUE      (1u)
    #define SM_START_MESSAGE   (2u)
    #define SM_SEND_MESSAGE    (3u)

    switch(curHTTP.smPost)
    {
        case SM_READ_NAME:
            // Read the next variable name.  If a complete name is
            // not found, request more data.  This function will
            // automatically truncate invalid data to prevent
            // buffer overflows.
            if(HTTPReadPostName(temp,16) == HTTP_READ_INCOMPLETE)
                return HTTP_IO_NEED_DATA;

            // Save "to" values to curHTTP.data[0:49]
            if(!strcmppgm2ram((char*)temp, (ROM char*)"to"))
                dest = curHTTP.data;

            // Save "subject" values to curHTTP.data[50:99]
            else if(!strcmppgm2ram((char*)temp, (ROM char*)"subject"))
                dest = curHTTP.data + 50;

            // When a "msg" is encountered, start sending
            else if(!strcmppgm2ram((char*)temp, (ROM char*)"msg"))
            {
                curHTTP.smPost = SM_START_MESSAGE;
                break;
            }

            // Ignore unexpected values
            else
                dest = NULL;

            // Move to the next state, but do not break yet
            curHTTP.smPost = SM_READ_VALUE;

        case SM_READ_VALUE:
            // Read the next value.  If a complete value is
            // not found, request more data.  This function will
            // automatically truncate invalid data to prevent
            // buffer overflows.
            if(HTTPReadPostValue(dest,50) == HTTP_READ_INCOMPLETE)
                return HTTP_IO_NEED_DATA;

            // Return to read a new name
            curHTTP.smPost = SM_READ_NAME;
            break;

        case SM_START_MESSAGE:
            // TODO: Perform necessary tasks to start sending the message.

            // Move on to sending the message body
            curHTTP.smPost = SM_SEND_MESSAGE;
            break;

        case SM_SEND_MESSAGE:
            // The message may be longer than the TCP buffer can hold
            // at once.  To avoid errors, read the data piece by
            // piece and send it to the e-mail module.  This requires
            // using TCP functions directly.

            // Send all remaining data
            while(curHTTP.byteCount > 0)
            {
                // First check if data is ready
                if(TCPIsGetReady(sktHTTP) == 0)
                    return HTTP_IO_NEED_DATA;

                // TODO: Read data with TCPGetArray and send
                //       it to the e-mail module.
            }

            // Process is complete
            return HTTP_IO_DONE;
    }

    // Assume return for state machine convenience.
    // Do not return HTTP_IO_NEED_DATA here by default, because
    // doing so when more data will not arrive is cause for
    // the HTTP2 server to return an error to the user.
    return HTTP_IO_WAITING;
}

The previous example uses the HTTPReadPostName and HTTPReadPostValue functions, and also demonstrates using the need to use TCPIsGetReady, TCPGet, and TCPGetArray when longer values are expected. For applications that will receive and react to parameters immediately and have no need for a state machine, a simple while loop can be written around HTTPReadPostPair to accomplish the callback. The HTTPPostLCD function in the TCPIP Demo App provides a simple example of this.

For more examples, refer to CustomHTTPApp.c in the TCPIP Demo App project.

Stack API > HTTP2 Server > Features > Form Processing


HTTP2 Authentication

Contents | Index | Home
Previous | Up | Next
HTTP2 Authentication

The HTTP protocol provides a method for servers to request a user name and password from a client before granting access to a page. The HTTP2 server supports this authentication mechanism, allowing developers to require valid credentials for access to some or all pages.

Authentication functionality is supported by two user-provided callback functions. The first, HTTPNeedsAuth, determines if the requested page requires valid credentials to proceed. The second, HTTPCheckAuth, checks the user name and password against an accepted list and determines whether to grant or deny access. This split between two callback functions is necessitated by the nature of the HTTP protocol and the low-memory architecture of the HTTP2 server. In cases where different credentials or sets of credentials may be accepted for different pages, the two functions communicate with each other through a single byte stored in curHTTP.isAuthorized.

Requiring Authentication

When a request is first made, the function HTTPNeedsAuth is called to determine if that page needs password protection. This function returns a value to instruct the HTTP2 server how to proceed. The most significant bit indicates whether or not access is granted. That is, values 0x80 and higher allow access unconditionally, while values 0x79 and lower will require a user name and password at a later point. The value returned is stored as curHTTP.isAuthorized so that it can be accessed by future callback functions.

The following example is the simplest case, in which all files require a password for access:

Copy Code
BYTE HTTPNeedsAuth(BYTE* cFile)
{
    return 0x00;
}

In some cases, only certain files will need to be protected. The second example requires a password for any file located in the /treasure folder:

Copy Code
BYTE HTTPNeedsAuth(BYTE* cFile)
{
    // Compare to "/treasure" folder.  Don't use strcmp here, because
    // cFile has additional path info such as "/treasure/gold.htm"
    if(!memcmppgm2ram((void*)cFile, (ROM void*)"treasure", 8))
        return 0x00;

    return 0x80;
}

More complex uses could require an administrative user to access the /admin folder, while any authenticated user can access the rest of the site. The third example requires a different set of user name and password combinations for the /admin folder versus the rest of the site:

Copy Code
#define HTTP_AUTH_ADMIN     (0x00)
#define HTTP_AUTH_OTHER     (0x01)

BYTE HTTPNeedsAuth(BYTE* cFile)
{
    // Return a specific code for admin users
    if(!memcmppgm2ram((void*)cFile, (ROM void*)"admin", 5))
        return HTTP_AUTH_ADMIN;

    return HTTP_AUTH_OTHER;
}
Validating Credentials

The HTTPCheckAuth function determines if the supplied user name and password are valid to access this resource. Again, the most significant bit indicates whether or not access is granted. The value returned is also stored as curHTTP.isAuthorized so that it can be accessed by future callback functions.

The following example is the simplest case, in which one user/password pair is accepted for all pages:

Copy Code
BYTE HTTPCheckAuth(BYTE* cUser, BYTE* cPass)
{
    if(!strcmppgm2ram((char*)cUser, (ROM char*)"AliBaba") &&
       !strcmppgm2ram((char*)cPass, (ROM char*)"Open Sesame!") )
        return 0x80;

    return 0x00;
}

In some cases, you may have multiple users with various levels of access. The following example satisfies the needs used in the third example of HTTPNeedsAuth above:

Copy Code
BYTE HTTPCheckAuth(BYTE* cUser, BYTE* cPass)
{
    // Check for admin users first
    if(curHTTP.isAuthorized == HTTP_AUTH_ADMIN &&
       !strcmppgm2ram((char*)cUser, (ROM char*)"admin") &&
       !strcmppgm2ram((char*)cPass, (ROM char*)"s3cREt") )
        return 0x80;

    if(!strcmppgm2ram((char*)cUser, (ROM char*)"kate") &&
       !strcmppgm2ram((char*)cPass, (ROM char*)"puppies!") )
        return 0x80;

    return 0x00;
}

More complex uses are certainly feasible. Many applications may choose to store the user names and passwords in EEPROM or other non-volatile storage so that they may be updated by the end-user. Some applications may wish to return various values above 0x80 in HTTPCheckAuth so that later callback functions can determine which user logged in. The flexibility of these functions provides for many more possibilities that are not documented here but can be developed in just a few hours.

Stack API > HTTP2 Server > Features > Authentication


HTTP2 Cookies

Contents | Index | Home
Previous | Up | Next
HTTP2 Cookies

By design, HTTP is a session-less and state-less protocol; every connection is an independent session with no relation to another. Cookies were added to the protocol description to solve this problem. This feature allows a web server to store small bits of text in a user's browser. These values will be returned to the server with every request, allowing the server to associate session variables with a request. Cookies are typically used for more advanced authentication systems.

Best practice is generally to store the bulk of the data on the server, and store only a unique identifier with the browser. This cuts down on data overhead and ensures that the user cannot modify the values stored with the session. However, logic must be implemented in the server to expire old sessions and allocate memory for new ones. If sensitive data is being stored, it is also important that the identifier be random enough so as to prevent stealing or spoofing another user's cookies.

Retrieving Cookies

In the HTTP2 server, cookies are retrieved automatically. They are stored in curHTTP.data, just as any other GET form argument or URL parameter would be. The proper place to parse these values is therefore in the HTTPExecuteGet callback using the HTTPGetArg or HTTPGetROMArg functions to locate the values.

This model consumes some of the limited space available for URL parameters. Ensure that cookies do not consume more space than is available (as defined by HTTP_MAX_DATA_LEN) and that they will fit after any data that may be submitted via a GET form. If enough space is not available, the cookies will be truncated.

Setting Cookies

Cookies can be set in HTTPExecuteGet or HTTPExecutePost. To set a cookie, store the name/value pairs in curHTTP.data as a series of null-terminated strings. Then set, curHTTP.hasArgs equal to the number of name/value pairs to be set. For example, the following code sets a cookie indicating a user's preference for a type of cookie:

Copy Code
void HTTPExecuteGet(void)
{
    ...

    // Set a cookie
    strcpypgm2ram((char*)curHTTP.data, (ROM char*)"flavor\0oatmeal raisin");
    curHTTP.hasArgs = 1;

    ...
}

After this, all future requests from this browser will include the parameter "flavor" in curHTTP.data, along with the associated value of "oatmeal raisin".

Stack API > HTTP2 Server > Features > Cookies


HTTP2 Compression

Contents | Index | Home
Previous | Up | Next
HTTP2 Compression

All modern web browsers can receive files encoded with GZIP compression. For static files (those without dynamic variables), this can decrease the amount of data transmitted by as much as 60%.

The MPFS2 Utility will automatically determine which files can benefit from GZIP compression, and will store the compressed file in the MPFS2 image when possible. This generally includes all JavaScript and CSS files. (Images are typically already compressed, so the MPFS2 Utility will generally decide it is better to store them uncompressed.) This HTTP server will then seamlessly return this compressed file to the browser. Less non-volatile storage space will be required for the MPFS2 image, and faster transfers back to the client will result. No special configuration is required for this feature.

To prevent certain extensions from being compressed, use the Advanced Settings dialog in the MPFS2 Utility.

Stack API > HTTP2 Server > Features > Compression


HTTP2 Public Members

Contents | Index | Home
Previous | Up | Next
HTTP2 Public Members

The following functions and variables are accessible or implemented by the stack application.

Enumerations
Name | Description
HTTP_IO_RESULT | Result states for execution callbacks
HTTP_READ_STATUS | Result states for HTTPPostReadName and HTTPPostReadValue
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.
HTTPGetArg | Locates a form field value in a given data array.
HTTPGetROMArg | Locates a form field value in a given data array.
HTTPNeedsAuth | Determines if a given file name requires authentication
HTTPPrint_varname | Inserts dynamic content into a web page
HTTPReadPostName | Reads a name from a URL encoded string in the TCP buffer.
HTTPReadPostValue | Reads a value from a URL encoded string in the TCP buffer.
HTTPURLDecode | Parses a string from URL encoding to plain-text.
Macros
Name | Description
HTTPReadPostPair | Reads a name and value pair from a URL encoded string in the TCP buffer.
sktHTTP | Access the current socket
Module

HTTP2 Server

Structures
Name | Description
HTTP_CONN | Stores extended state data for each connection
Variables
Name | Description
curHTTP | Current HTTP connection state
Stack API > HTTP2 Server > Public Members


curHTTP Variable

Contents | Index | Home
Previous | Up | Next
curHTTP Variable
C
HTTP_CONN curHTTP;
Description

Current HTTP connection state

Stack API > HTTP2 Server > Public Members > curHTTP Variable


HTTP_CONN Structure

Contents | Index | Home
Previous | Up | Next
HTTP_CONN Structure
C
typedef struct {
  DWORD byteCount;
  DWORD nextCallback;
  DWORD callbackID;
  DWORD callbackPos;
  BYTE * ptrData;
  BYTE * ptrRead;
  MPFS_HANDLE file;
  MPFS_HANDLE offsets;
  BYTE hasArgs;
  BYTE isAuthorized;
  HTTP_STATUS httpStatus;
  HTTP_FILE_TYPE fileType;
  BYTE data[HTTP_MAX_DATA_LEN];
  BYTE smPost;
} HTTP_CONN;
Description

Stores extended state data for each connection

Members
Members | Description
DWORD byteCount; | How many bytes have been read so far
DWORD nextCallback; | Byte index of the next callback
DWORD callbackID; | Callback ID to execute, also used as watchdog timer
DWORD callbackPos; | Callback position indicator
BYTE * ptrData; | Points to first free byte in data
BYTE * ptrRead; | Points to current read location
MPFS_HANDLE file; | File pointer for the file being served
MPFS_HANDLE offsets; | File pointer for any offset info being used
BYTE hasArgs; | True if there were get or cookie arguments
BYTE isAuthorized; | 0x00-0x79 on fail, 0x80-0xff on pass
HTTP_STATUS httpStatus; | Request method/status
HTTP_FILE_TYPE fileType; | File type to return with Content-Type
BYTE data[HTTP_MAX_DATA_LEN]; | General purpose data buffer
BYTE smPost; | POST state machine variable
Stack API > HTTP2 Server > Public Members > HTTP_CONN Structure


HTTP_IO_RESULT Enumeration

Contents | Index | Home
Previous | Up | Next
HTTP_IO_RESULT Enumeration
C
typedef enum {
  HTTP_IO_DONE = 0u,
  HTTP_IO_NEED_DATA,
  HTTP_IO_WAITING
} HTTP_IO_RESULT;
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
Stack API > HTTP2 Server > Public Members > HTTP_IO_RESULT Enumeration


HTTP_READ_STATUS Enumeration

Contents | Index | Home
Previous | Up | Next
HTTP_READ_STATUS Enumeration
C
typedef enum {
  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.
Stack API > HTTP2 Server > Public Members > HTTP_READ_STATUS Enumeration


HTTPCheckAuth Function

Contents | Index | Home
Previous | Up | Next
HTTPCheckAuth Function
C
BYTE HTTPCheckAuth(
    BYTE* cUser,
    BYTE* 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.

Preconditions

None

Parameters
Parameters | Description
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.

Stack API > HTTP2 Server > Public Members > HTTPCheckAuth Function


HTTPExecuteGet Function

Contents | Index | Home
Previous | Up | Next
HTTPExecuteGet Function
C
HTTP_IO_RESULT HTTPExecuteGet();
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, HTTPGetArg and HTTPGetROMArg 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

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.

Stack API > HTTP2 Server > Public Members > HTTPExecuteGet Function


HTTPExecutePost Function

Contents | Index | Home
Previous | Up | Next
HTTPExecutePost Function
C
HTTP_IO_RESULT HTTPExecutePost();
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 TCPGet or TCPGetArray in order to retrieve bytes. When this is done, curHTTP.byteCount MUST be updated to reflect how many bytes now remain. The functions TCPFind, TCPFindString, TCPFindROMString, TCPFindArray, and TCPFindROMArray may be helpful to locate data in the TCP buffer.

In general, data submitted from web forms via POST is URL encoded. The HTTPURLDecode 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

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.

Stack API > HTTP2 Server > Public Members > HTTPExecutePost Function


HTTPGetArg Function

Contents | Index | Home
Previous | Up | Next
HTTPGetArg Function
C
BYTE* HTTPGetArg(
    BYTE* cData,
    BYTE* 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.

Stack API > HTTP2 Server > Public Members > HTTPGetArg Function


HTTPGetROMArg Function

Contents | Index | Home
Previous | Up | Next
HTTPGetROMArg Function
C
BYTE* HTTPGetROMArg(
    BYTE* cData,
    ROM BYTE* 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

This function is aliased to HTTPGetArg on non-PIC18 platforms.

Stack API > HTTP2 Server > Public Members > HTTPGetROMArg Function


HTTPNeedsAuth Function

Contents | Index | Home
Previous | Up | Next
HTTPNeedsAuth Function
C
BYTE HTTPNeedsAuth(
    BYTE* 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
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.

Stack API > HTTP2 Server > Public Members > HTTPNeedsAuth Function


HTTPPrint_varname Function

Contents | Index | Home
Previous | Up | Next
HTTPPrint_varname Function
C
void HTTPPrint_varname(
    WORD wParam1,
    WORD 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 HTTP2 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 HTTPPrint.h, which is automatically generated by the MPFS2 Utility. The prototype will have WORD parameters included for each parameter passed in the dynamic variable. For example, the variable "~myArray(2,6)~" will generate the prototype "void HTTPPrint_varname(WORD, WORD);".

When called, this function should write its output directly to the TCP socket using any combination of TCPIsPutReady, TCPPut, TCPPutArray, TCPPutString, TCPPutROMArray, and TCPPutROMString.

Before calling, the HTTP2 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
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.

Stack API > HTTP2 Server > Public Members > HTTPPrint_varname Function


HTTPReadPostName Function

Contents | Index | Home
Previous | Up | Next
HTTPReadPostName Function
C
HTTP_READ_STATUS HTTPReadPostName(
    BYTE* cData,
    WORD 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 curHTTP.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
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
HTTP_READ_INCOMPLETE | entire name was not yet in the buffer, so call this function again later to retrieve
Stack API > HTTP2 Server > Public Members > HTTPReadPostName Function


HTTPReadPostPair Macro

Contents | Index | Home
Previous | Up | Next
HTTPReadPostPair Macro
C
#define HTTPReadPostPair(cData, wLen) HTTPReadPostValue(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
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 HTTPReadPostValue, since they effectively perform the same task. The name is provided only for completeness.

Stack API > HTTP2 Server > Public Members > HTTPReadPostPair Macro


HTTPReadPostValue Function

Contents | Index | Home
Previous | Up | Next
HTTPReadPostValue Function
C
HTTP_READ_STATUS HTTPReadPostValue(
    BYTE* cData,
    WORD 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 curHTTP.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 curHTTP.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
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
Stack API > HTTP2 Server > Public Members > HTTPReadPostValue Function


HTTPURLDecode Function

Contents | Index | Home
Previous | Up | Next
HTTPURLDecode Function
C
BYTE* HTTPURLDecode(
    BYTE* 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.

Stack API > HTTP2 Server > Public Members > HTTPURLDecode Function


sktHTTP Macro

Contents | Index | Home
Previous | Up | Next
sktHTTP Macro
C
#define sktHTTP httpStubs[curHTTPID].socket        // Access the current socket
Description

Access the current socket

Stack API > HTTP2 Server > Public Members > sktHTTP Macro


HTTP2 Stack Members

Contents | Index | Home
Previous | Up | Next
HTTP2 Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
HTTPInit | Initializes the HTTP server module.
HTTPServer | Performs periodic tasks for the HTTP2 module.
Module

HTTP2 Server

Stack API > HTTP2 Server > Stack Members


HTTPInit Function

Contents | Index | Home
Previous | Up | Next
HTTPInit Function
C
void HTTPInit();
Description

Sets all HTTP sockets to the listening state, and initializes the state machine and file handles for each connection. If SSL is enabled, opens a socket on that port as well.

Preconditions

TCP must already be initialized.

Returns

None

Remarks

This function is called only one during lifetime of the application.

Stack API > HTTP2 Server > Stack Members > HTTPInit Function


HTTPServer Function

Contents | Index | Home
Previous | Up | Next
HTTPServer Function
C
void HTTPServer();
Description

Browses through each open connection and attempts to process any pending operations.

Preconditions

HTTPInit() must already be called.

Returns

None

Remarks

This function acts as a task (similar to one in an RTOS). It performs its task in a co-operative manner, and the main application must call this function repeatedly to ensure that all open or new connections are served in a timely fashion.

Stack API > HTTP2 Server > Stack Members > HTTPServer Function


HTTP2 Internal Members

Contents | Index | Home
Previous | Up | Next
HTTP2 Internal Members

The following functions and variables are designated as internal to the HTTP2 module.

Enumerations
Name | Description
HTTP_FILE_TYPE | File type definitions
HTTP_STATUS | Supported Commands and Server Response Codes
SM_HTTP2 | Basic HTTP Connection State Machine
Functions
Name | Description
HTTPHeaderParseAuthorization | Parses the "Authorization:" header for a request and verifies the credentials.
HTTPHeaderParseContentLength | Parses the "Content-Length:" header for a request.
HTTPHeaderParseCookie | Parses the "Cookie:" headers for a request and stores them as GET variables.
HTTPHeaderParseLookup | Calls the appropriate header parser based on the index of the header that was read from the request.
HTTPIncFile | Writes a file byte-for-byte to the currently loaded TCP socket.
HTTPLoadConn | Switches the currently loaded connection for the HTTP2 module.
HTTPMPFSUpload | Saves a file uploaded via POST as the new MPFS image in EEPROM or external Flash.
HTTPProcess | Performs any pending operations for the currently loaded HTTP connection.
HTTPReadTo | Reads to a buffer until a specified delimiter character.
HTTPSendFile | Serves up the next chunk of curHTTP's file, up to a) available TX FIFO space or b) the next callback index, whichever comes first.
Macros
Name | Description
HTTP_CACHE_LEN | Max lifetime (sec) of static responses as string
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_TIMEOUT | Max time (sec) to await more data before timing out and disconnecting the socket
HTTPS_PORT | Define the listening port for the HTTPS server (if STACK_USE_SSL_SERVER is enabled)
smHTTP | Access the current state machine
RESERVED_HTTP_MEMORY | Macro indicating how much RAM to allocate on an ethernet controller to store HTTP state data.
Module

HTTP2 Server

Structures
Name | Description
HTTP_STUB | HTTP Connection Struct Stores partial state data for each connection Meant for storage in fast access RAM
Variables
Name | Description
curHTTPID | ID of the currently loaded HTTP_CONN
httpContentTypes | Content-type strings corresponding to HTTP_FILE_TYPE
httpFileExtensions |
HTTPRequestHeaders | Header strings for which we'd like to parse
HTTPResponseHeaders | Initial response strings (Corresponding to HTTP_STATUS)
httpStubs | HTTP stubs with state machine and socket
Stack API > HTTP2 Server > Internal Members


curHTTPID Variable

Contents | Index | Home
Previous | Up | Next
curHTTPID Variable
C
BYTE curHTTPID;
Description

ID of the currently loaded HTTP_CONN

Stack API > HTTP2 Server > Internal Members > curHTTPID Variable


HTTP_CACHE_LEN Macro

Contents | Index | Home
Previous | Up | Next
HTTP_CACHE_LEN Macro
C
#define HTTP_CACHE_LEN ("600")    // Max lifetime (sec) of static responses as string
Description

Max lifetime (sec) of static responses as string

Stack API > HTTP2 Server > Internal Members > HTTP_CACHE_LEN Macro


HTTP_FILE_TYPE Enumeration

Contents | Index | Home
Previous | Up | Next
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
Stack API > HTTP2 Server > Internal Members > HTTP_FILE_TYPE Enumeration


HTTP_MAX_DATA_LEN Macro

Contents | Index | Home
Previous | Up | Next
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)

Stack API > HTTP2 Server > Internal Members > HTTP_MAX_DATA_LEN Macro


HTTP_MAX_HEADER_LEN Macro

Contents | Index | Home
Previous | Up | Next
HTTP_MAX_HEADER_LEN Macro
C
#define HTTP_MAX_HEADER_LEN (15u)
Description

Set to length of longest string above

Stack API > HTTP2 Server > Internal Members > HTTP_MAX_HEADER_LEN Macro


HTTP_MIN_CALLBACK_FREE Macro

Contents | Index | Home
Previous | Up | Next
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

Stack API > HTTP2 Server > Internal Members > HTTP_MIN_CALLBACK_FREE Macro


HTTP_PORT Macro

Contents | Index | Home
Previous | Up | Next
HTTP_PORT Macro
C
#define HTTP_PORT (80u)
Description

Define the listening port for the HTTP server

Stack API > HTTP2 Server > Internal Members > HTTP_PORT Macro


HTTP_STATUS Enumeration

Contents | Index | Home
Previous | Up | Next
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_MPFS_FORM,
  HTTP_MPFS_UP,
  HTTP_MPFS_OK,
  HTTP_MPFS_ERROR,
  HTTP_REDIRECT,
  HTTP_SSL_REQUIRED
} 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_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
HTTP_REDIRECT | 302 Redirect will be returned
HTTP_SSL_REQUIRED | 403 Forbidden is returned, indicating SSL is required
Stack API > HTTP2 Server > Internal Members > HTTP_STATUS Enumeration


HTTP_STUB Structure

Contents | Index | Home
Previous | Up | Next
HTTP_STUB Structure
C
typedef struct {
  SM_HTTP2 sm;
  TCP_SOCKET socket;
} HTTP_STUB;
Description

HTTP Connection Struct Stores partial state data for each connection Meant for storage in fast access RAM

Members
Members | Description
SM_HTTP2 sm; | Current connection state
TCP_SOCKET socket; | Socket being served
Stack API > HTTP2 Server > Internal Members > HTTP_STUB Structure


HTTP_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
HTTP_TIMEOUT Macro
C
#define HTTP_TIMEOUT (45u)    // Max time (sec) to await more data before timing out and disconnecting the socket
Description

Max time (sec) to await more data before timing out and disconnecting the socket

Stack API > HTTP2 Server > Internal Members > HTTP_TIMEOUT Macro


httpContentTypes Variable

Contents | Index | Home
Previous | Up | Next
httpContentTypes Variable
C
ROM char * ROM httpContentTypes[HTTP_UNKNOWN+1] = { "text/plain", "text/html", "text/html", "text/html", "text/xml", "text/css", "image/gif", "image/png", "image/jpeg", "application/java-vm", "audio/x-wave", "" };
Description

Content-type strings corresponding to HTTP_FILE_TYPE

Stack API > HTTP2 Server > Internal Members > httpContentTypes Variable


httpFileExtensions Variable

Contents | Index | Home
Previous | Up | Next
httpFileExtensions Variable
C
ROM char * ROM httpFileExtensions[HTTP_UNKNOWN+1] = { "txt", "htm", "html", "cgi", "xml", "css", "gif", "png", "jpg", "cla", "wav", "\0\0\0" };
Stack API > HTTP2 Server > Internal Members > httpFileExtensions Variable


HTTPHeaderParseAuthorization Function

Contents | Index | Home
Previous | Up | Next
HTTPHeaderParseAuthorization Function
C
static void HTTPHeaderParseAuthorization();
Description

Parses the "Authorization:" header for a request. For example, "BASIC YWRtaW46cGFzc3dvcmQ=" is decoded to a user name of "admin" and a password of "password". Once read, HTTPCheckAuth is called from CustomHTTPApp.c to determine if the credentials are acceptable.

The return value of HTTPCheckAuth is saved in curHTTP.isAuthorized for later use by the application.

Preconditions

None

Returns

None

Remarks

This function is ony available when HTTP_USE_AUTHENTICATION is defined.

Stack API > HTTP2 Server > Internal Members > HTTPHeaderParseAuthorization Function


HTTPHeaderParseContentLength Function

Contents | Index | Home
Previous | Up | Next
HTTPHeaderParseContentLength Function
C
static void HTTPHeaderParseContentLength();
Description

Parses the "Content-Length:" header to determine how many bytes of POST data to expect after the request. This value is stored in curHTTP.byteCount.

Preconditions

None

Returns

None

Remarks

This function is ony available when HTTP_USE_POST is defined.

Stack API > HTTP2 Server > Internal Members > HTTPHeaderParseContentLength Function


HTTPHeaderParseCookie Function

Contents | Index | Home
Previous | Up | Next
HTTPHeaderParseCookie Function
C
static void HTTPHeaderParseCookie();
Description

Parses the "Cookie:" headers for a request. For example, "Cookie: name=Wile+E.+Coyote; order=ROCKET_LAUNCHER" is decoded to "name=Wile+E.+Coyote&order=ROCKET_LAUNCHER&" and stored as any other GET variable in curHTTP.data.

The user application can easily access these values later using the HTTPGetArg() and HTTPGetROMArg() functions.

Preconditions

None

Returns

None

Remarks

This function is ony available when HTTP_USE_COOKIES is defined.

Stack API > HTTP2 Server > Internal Members > HTTPHeaderParseCookie Function


HTTPHeaderParseLookup Function

Contents | Index | Home
Previous | Up | Next
HTTPHeaderParseLookup Function
C
static void HTTPHeaderParseLookup(
    BYTE i
);
Description

Calls the appropriate header parser based on the index of the header that was read from the request.

Preconditions

None

Parameters
Parameters | Description
i | the index of the string found in HTTPRequestHeaders
Return Values
Return Values | Description
TRUE | the end of the file was reached and reading is done
FALSE | more data remains to be read
Stack API > HTTP2 Server > Internal Members > HTTPHeaderParseLookup Function


HTTPIncFile Function

Contents | Index | Home
Previous | Up | Next
HTTPIncFile Function
C
void HTTPIncFile(
    ROM BYTE* 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 curHTTP.callbackPos is 0, the file is opened and as many bytes as possible are written. The current position is then saved to curHTTP.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, curHTTP.callbackPos is set back to 0 to indicate completion.

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.

Stack API > HTTP2 Server > Internal Members > HTTPIncFile Function


HTTPLoadConn Function

Contents | Index | Home
Previous | Up | Next
HTTPLoadConn Function
C
static void HTTPLoadConn(
    BYTE hHTTP
);
Description

Saves the currently loaded HTTP connection back to Ethernet buffer RAM, then loads the selected connection into curHTTP in local RAM for processing.

Preconditions

None

Parameters
Parameters | Description
hHTTP | the connection ID to load
Returns

None

Stack API > HTTP2 Server > Internal Members > HTTPLoadConn Function


HTTPMPFSUpload Function

Contents | Index | Home
Previous | Up | Next
HTTPMPFSUpload Function
C
static HTTP_IO_RESULT HTTPMPFSUpload();
Description

Allows the MPFS image in EEPROM or external Flash to be updated via a web page by accepting a file upload and storing it to the external memory.

Preconditions

MPFSFormat() has been called.

Return Values
Return Values | Description
HTTP_IO_DONE | on success
HTTP_IO_NEED_DATA | if more data is still expected
Remarks

This function is only available when MPFS uploads are enabled and the MPFS image is stored in EEPROM.

Stack API > HTTP2 Server > Internal Members > HTTPMPFSUpload Function


HTTPProcess Function

Contents | Index | Home
Previous | Up | Next
HTTPProcess Function
C
static void HTTPProcess();
Description

Performs any pending operations for the currently loaded HTTP connection.

Preconditions

HTTPInit() and HTTPLoadConn() have been called.

Returns

None

Stack API > HTTP2 Server > Internal Members > HTTPProcess Function


HTTPReadTo Function

Contents | Index | Home
Previous | Up | Next
HTTPReadTo Function
C
static HTTP_READ_STATUS HTTPReadTo(
    BYTE delim,
    BYTE* buf,
    WORD len
);
Description

Reads from the TCP buffer to cData until either cDelim is reached, or until wLen - 2 bytes have been read. The value read is saved to cData and null terminated. (wLen - 2 is used so that the value can be passed to HTTPURLDecode later, which requires a null terminator plus one extra free byte.)

The delimiter character is removed from the buffer, but not saved to cData. If all data cannot fit into cData, it will still be removed from the buffer but will not be saved anywhere.

This function properly updates curHTTP.byteCount by decrementing it by the number of bytes read.

Preconditions

None

Parameters
Parameters | Description
cDelim | the character at which to stop reading, or NULL to read to the end of the buffer
cData | where to store the data being read
wLen | how many bytes can be written to cData
Return Values
Return Values | Description
HTTP_READ_OK | data was successfully read
HTTP_READ_TRUNCTATED | entire data could not fit in the buffer, so the data was truncated and data has been lost
HTTP_READ_INCOMPLETE | delimiter character was not found
Stack API > HTTP2 Server > Internal Members > HTTPReadTo Function


HTTPRequestHeaders Variable

Contents | Index | Home
Previous | Up | Next
HTTPRequestHeaders Variable
C
ROM char * ROM HTTPRequestHeaders[] = { "Cookie:", "Authorization:", "Content-Length:" };
Description

Header strings for which we'd like to parse

Stack API > HTTP2 Server > Internal Members > HTTPRequestHeaders Variable


HTTPResponseHeaders Variable

Contents | Index | Home
Previous | Up | Next
HTTPResponseHeaders Variable
C
ROM char * ROM HTTPResponseHeaders[] = { "HTTP/1.1 200 OK\r\nConnection: close\r\n", "HTTP/1.1 200 OK\r\nConnection: close\r\n", "HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n400 Bad Request: can't handle Content-Length\r\n", "HTTP/1.1 401 Unauthorized\r\nWWW-Authenticate: Basic realm=\"Protected\"\r\nConnection: close\r\n\r\n401 Unauthorized: Password required\r\n", "HTTP/1.1 404 Not found\r\nConnection: close\r\nContent-Type: text/html\r\n\r\n404: File not found<br>Use <a href=\"/" HTTP_MPFS_UPLOAD "\">MPFS Upload</a> to program web pages\r\n", "HTTP/1.1 404 Not found\r\nConnection: close\r\n\r\n404: File not found\r\n", "HTTP/1.1 414 Request-URI Too Long\r\nConnection: close\r\n\r\n414 Request-URI Too Long: Buffer overflow detected\r\n", "HTTP/1.1 500 Internal Server Error\r\nConnection: close\r\n\r\n500 Internal Server Error: Expected data not present\r\n", "HTTP/1.1 501 Not Implemented\r\nConnection: close\r\n\r\n501 Not Implemented: Only GET and POST supported\r\n", "HTTP/1.1 200 OK\r\nConnection: close\r\nContent-Type: text/html\r\n\r\n<html><body style=\"margin:100px\"><form method=post action=\"/" HTTP_MPFS_UPLOAD "\" enctype=\"multipart/form-data\"><b>MPFS Image Upload</b><p><input type=file name=i size=40> &nbsp; <input type=submit value=\"Upload\"></form></body></html>", "", "HTTP/1.1 200 OK\r\nConnection: close\r\nContent-Type: text/html\r\n\r\n<html><body style=\"margin:100px\"><b>MPFS Update Successful</b><p><a href=\"/\">Site main page</a></body></html>", "HTTP/1.1 500 Internal Server Error\r\nConnection: close\r\nContent-Type: text/html\r\n\r\n<html><body style=\"margin:100px\"><b>MPFS Image Corrupt or Wrong Version</b><p><a href=\"/" HTTP_MPFS_UPLOAD "\">Try again?</a></body></html>", "HTTP/1.1 302 Found\r\nConnection: close\r\nLocation: ", "HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n403 Forbidden: SSL Required - use HTTPS\r\n" };
Description

Initial response strings (Corresponding to HTTP_STATUS)

Stack API > HTTP2 Server > Internal Members > HTTPResponseHeaders Variable


HTTPS_PORT Macro

Contents | Index | Home
Previous | Up | Next
HTTPS_PORT Macro
C
#define HTTPS_PORT (443u)
Description

Define the listening port for the HTTPS server (if STACK_USE_SSL_SERVER is enabled)

Stack API > HTTP2 Server > Internal Members > HTTPS_PORT Macro


HTTPSendFile Function

Contents | Index | Home
Previous | Up | Next
HTTPSendFile Function
C
static BOOL HTTPSendFile();
Description

Serves up the next chunk of curHTTP's file, up to a) available TX FIFO space or b) the next callback index, whichever comes first.

Preconditions

curHTTP.file and curHTTP.offsets have both been opened for reading.

Return Values
Return Values | Description
TRUE | the end of the file was reached and reading is done
FALSE | more data remains to be read
Stack API > HTTP2 Server > Internal Members > HTTPSendFile Function


httpStubs Variable

Contents | Index | Home
Previous | Up | Next
httpStubs Variable
C
HTTP_STUB httpStubs[MAX_HTTP_CONNECTIONS];
Description

HTTP stubs with state machine and socket

Stack API > HTTP2 Server > Internal Members > httpStubs Variable


SM_HTTP2 Enumeration

Contents | Index | Home
Previous | Up | Next
SM_HTTP2 Enumeration
C
typedef enum {
  SM_HTTP_IDLE = 0u,
  SM_HTTP_PARSE_REQUEST,
  SM_HTTP_PARSE_HEADERS,
  SM_HTTP_AUTHENTICATE,
  SM_HTTP_PROCESS_GET,
  SM_HTTP_PROCESS_POST,
  SM_HTTP_PROCESS_REQUEST,
  SM_HTTP_SERVE_HEADERS,
  SM_HTTP_SERVE_COOKIES,
  SM_HTTP_SERVE_BODY,
  SM_HTTP_SEND_FROM_CALLBACK,
  SM_HTTP_DISCONNECT
} SM_HTTP2;
Description

Basic HTTP Connection State Machine

Members
Members | Description
SM_HTTP_IDLE = 0u | Socket is idle
SM_HTTP_PARSE_REQUEST | Parses the first line for a file name and GET args
SM_HTTP_PARSE_HEADERS | Reads and parses headers one at a time
SM_HTTP_AUTHENTICATE | Validates the current authorization state
SM_HTTP_PROCESS_GET | Invokes user callback for GET args or cookies
SM_HTTP_PROCESS_POST | Invokes user callback for POSTed data
SM_HTTP_PROCESS_REQUEST | Begins the process of returning data
SM_HTTP_SERVE_HEADERS | Sends any required headers for the response
SM_HTTP_SERVE_COOKIES | Adds any cookies to the response
SM_HTTP_SERVE_BODY | Serves the actual content
SM_HTTP_SEND_FROM_CALLBACK | Invokes a dynamic variable callback
SM_HTTP_DISCONNECT | Disconnects the server and closes all files
Stack API > HTTP2 Server > Internal Members > SM_HTTP2 Enumeration


smHTTP Macro

Contents | Index | Home
Previous | Up | Next
smHTTP Macro
C
#define smHTTP httpStubs[curHTTPID].sm            // Access the current state machine
Description

Access the current state machine

Stack API > HTTP2 Server > Internal Members > smHTTP Macro


RESERVED_HTTP_MEMORY Macro

Contents | Index | Home
Previous | Up | Next
RESERVED_HTTP_MEMORY Macro
C
#define RESERVED_HTTP_MEMORY ((DWORD)MAX_HTTP_CONNECTIONS * (DWORD)sizeof(HTTP_CONN))
Description

Macro indicating how much RAM to allocate on an ethernet controller to store HTTP state data.

Stack API > HTTP2 Server > Internal Members > RESERVED_HTTP_MEMORY Macro


ICMP

Contents | Index | Home
Previous | Up | Next
ICMP

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.

Topics
Name | Description
ICMP Public Members | Functions and variables accessible or implemented by the stack application
ICMP Internal Members | Functions and variables used internally by the ICMP module
Stack API > ICMP


ICMP Public Members

Contents | Index | Home
Previous | Up | Next
ICMP Public Members

The following functions and variables are accessible or implemented by the stack application.

Functions
Name | Description
ICMPBeginUsage | Claims ownership of the ICMP module.
ICMPSendPing | None
ICMPSendPingToHost | None
ICMPSendPingToHostROM | Begins the process of transmitting an ICMP echo request. This normally involves an ARP resolution procedure first.
ICMPGetReply | None
ICMPEndUsage | Gives up ownership of the ICMP module.
Macros
Name | Description
ICMPSendPingToHostROM | This is macro ICMPSendPingToHostROM.
Module

ICMP

Stack API > ICMP > Public Members


ICMPBeginUsage Function

Contents | Index | Home
Previous | Up | Next
ICMPBeginUsage Function
C
BOOL ICMPBeginUsage();
Description

Claims ownership of the ICMP module.

Preconditions

None

Returns

TRUE: You have successfully gained ownership of the ICMP client module and can now use the ICMPSendPing() and ICMPGetReply() functions. FALSE: Some other application is using the ICMP client module. Calling ICMPSendPing() will corrupt the other application's ping result.

Side Effects

None

Remarks

None

Stack API > ICMP > Public Members > ICMPBeginUsage Function


ICMPSendPing Function

Contents | Index | Home
Previous | Up | Next
ICMPSendPing Function
C
void ICMPSendPing(
    DWORD dwRemoteIP
);
Description

None

Preconditions

ICMPBeginUsage() returned TRUE

Parameters
Parameters | Description
dwRemoteIP | IP Address to ping. Must be stored big endian. Ex. 192.168.0.1 should be passed as 0x0100A8C0.
Returns

Begins the process of transmitting an ICMP echo request. This normally involves an ARP resolution procedure first.

Side Effects

None

Remarks

None

Stack API > ICMP > Public Members > ICMPSendPing Function


ICMPSendPingToHost Function

Contents | Index | Home
Previous | Up | Next
ICMPSendPingToHost Function
C
void ICMPSendPingToHost(
    BYTE * szRemoteHost
);
Description

None

Preconditions

ICMPBeginUsage() returned TRUE

Parameters
Parameters | Description
szRemoteHost | Host name to ping. Must be stored in RAM if being called by PIC18. Ex. www.microchip.com
Returns

Begins the process of transmitting an ICMP echo request. This normally involves an ARP resolution procedure first.

Side Effects

None

Remarks

None

Stack API > ICMP > Public Members > ICMPSendPingToHost Function


ICMPSendPingToHostROM Function

Contents | Index | Home
Previous | Up | Next
ICMPSendPingToHostROM Function
C
void ICMPSendPingToHostROM(
    ROM BYTE * szRemoteHost
);
Description

Begins the process of transmitting an ICMP echo request. This normally involves an ARP resolution procedure first.

Preconditions

ICMPBeginUsage() returned TRUE

Parameters
Parameters | Description
szRemoteHost | Host name to ping. Must be stored in ROM. Should only be called by PIC18. Ex. www.microchip.com
Returns

None

Side Effects

None

Remarks

None

Stack API > ICMP > Public Members > ICMPSendPingToHostROM Function


ICMPGetReply Function

Contents | Index | Home
Previous | Up | Next
ICMPGetReply Function
C
LONG ICMPGetReply();
Description

None

Preconditions

ICMPBeginUsage() returned TRUE and ICMPSendPing() was called

Returns

-3: Could not resolve hostname (DNS timeout or hostname invalid) -2: No response received yet -1: Operation timed out (longer than ICMP_TIMEOUT) has elapsed. >=0: Number of TICKs that elapsed between initial ICMP transmission and reception of a valid echo.

Side Effects

None

Remarks

None

Stack API > ICMP > Public Members > ICMPGetReply Function


ICMPEndUsage Function

Contents | Index | Home
Previous | Up | Next
ICMPEndUsage Function
C
void ICMPEndUsage();
Description

Gives up ownership of the ICMP module.

Preconditions

ICMPBeginUsage() was called by you and it returned TRUE.

Returns

Your ownership of the ICMP module is released. You can no longer use ICMPSendPing().

Side Effects

None

Remarks

None

Stack API > ICMP > Public Members > ICMPEndUsage Function


ICMPSendPingToHostROM Macro

Contents | Index | Home
Previous | Up | Next
ICMPSendPingToHostROM Macro
C
#define ICMPSendPingToHostROM(a) ICMPSendPingToHost((BYTE*)(a))
Description

This is macro ICMPSendPingToHostROM.

Stack API > ICMP > Public Members > ICMPSendPingToHostROM Macro


ICMP Internal Members

Contents | Index | Home
Previous | Up | Next
ICMP Internal Members

The following functions and variables are designated as internal to the ICMP module.

Functions
Name | Description
ICMPProcess | None
Macros
Name | Description
ICMP_TIMEOUT | ICMP Timeout Value
Module

ICMP

Structures
Name | Description
ICMP_PACKET | ICMP Packet Structure
Variables
Name | Description
ICMPFlags | ICMP Flag structure
ICMPState | ICMP State Machine Enumeration
ICMPTimer | ICMP tick timer variable
StaticVars | ICMP Static Variables
wICMPSequenceNumber | ICMP Sequence Number
Stack API > ICMP > Internal Members


ICMPProcess Function

Contents | Index | Home
Previous | Up | Next
ICMPProcess Function
C
void ICMPProcess(
    NODE_INFO * remote,
    WORD len
);
Description

None

Preconditions

MAC buffer contains ICMP type packet.

Parameters
Parameters | Description
*remote | Pointer to a NODE_INFO structure of the ping requester
len | Count of how many bytes the ping header and payload are in this IP packet
Returns

Generates an echo reply, if requested Validates and sets ICMPFlags.bReplyValid if a correct ping response to one of ours is received.

Side Effects

None

Remarks

None

Stack API > ICMP > Internal Members > ICMPProcess Function


ICMPFlags Variable

Contents | Index | Home
Previous | Up | Next
ICMPFlags Variable
C
struct {
  unsigned char bICMPInUse : 1;
  unsigned char bReplyValid : 1;
  unsigned char bRemoteHostIsROM : 1;
} ICMPFlags;
Description

ICMP Flag structure

Members
Members | Description
unsigned char bICMPInUse : 1; | Indicates that the ICMP Client is in use
unsigned char bReplyValid : 1; | Indicates that a correct Ping response to one of our pings was received
unsigned char bRemoteHostIsROM : 1; | Indicates that a remote host name was passed as a ROM pointer argument
Stack API > ICMP > Internal Members > ICMPFlags Variable


ICMP_PACKET Structure

Contents | Index | Home
Previous | Up | Next
ICMP_PACKET Structure
C
typedef struct {
  BYTE vType;
  BYTE vCode;
  WORD wChecksum;
  WORD wIdentifier;
  WORD wSequenceNumber;
  WORD wData;
} ICMP_PACKET;
Description

ICMP Packet Structure

Stack API > ICMP > Internal Members > ICMP_PACKET Structure


ICMPState Variable

Contents | Index | Home
Previous | Up | Next
ICMPState Variable
C
enum {
  SM_IDLE = 0,
  SM_DNS_SEND_QUERY,
  SM_DNS_GET_RESPONSE,
  SM_ARP_SEND_QUERY,
  SM_ARP_GET_RESPONSE,
  SM_ICMP_SEND_ECHO_REQUEST,
  SM_ICMP_GET_ECHO_RESPONSE
} ICMPState;
Description

ICMP State Machine Enumeration

Stack API > ICMP > Internal Members > ICMPState Variable


ICMP_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
ICMP_TIMEOUT Macro
C
#define ICMP_TIMEOUT (4ul*TICK_SECOND)
Description

ICMP Timeout Value

Stack API > ICMP > Internal Members > ICMP_TIMEOUT Macro


ICMPTimer Variable

Contents | Index | Home
Previous | Up | Next
ICMPTimer Variable
C
DWORD ICMPTimer;
Description

ICMP tick timer variable

Stack API > ICMP > Internal Members > ICMPTimer Variable


StaticVars Variable

Contents | Index | Home
Previous | Up | Next
StaticVars Variable
C
union {
  union {
    ROM BYTE * szROM;
    BYTE * szRAM;
  } RemoteHost;
  NODE_INFO ICMPRemote;
} StaticVars;
Description

ICMP Static Variables

Stack API > ICMP > Internal Members > StaticVars Variable


wICMPSequenceNumber Variable

Contents | Index | Home
Previous | Up | Next
wICMPSequenceNumber Variable
C
WORD wICMPSequenceNumber;
Description

ICMP Sequence Number

Stack API > ICMP > Internal Members > wICMPSequenceNumber Variable


MPFS2

Contents | Index | Home
Previous | Up | Next
MPFS2

The MPFS2 file system module provides a light-weight read-only file system that can be stored in external EEPROM, external serial Flash, or internal Flash program memory. This file system serves as the basis for the HTTP2 web server module, but is also used by the SNMP module and is available to other applications that require basic read-only storage capabilities.

The MPFS2 module includes an MPFS2 Utility that runs on your PC. This program builds MPFS2 images in various formats for use in the supported storage mediums. More information is available in the MPFS2 Utility section.

Using External Storage

For external storage, the MPFS2 file system supports Microchip 25LCxxx EEPROM parts for densities up to 1Mbit. SST 25VFxxxB serial Flash parts are also supported for densities up to 32Mbit.

To use external EEPROM storage, ensure that the configuration macro MPFS_USE_EEPROM is defined in TCPIPConfig.h. If you are using a 1Mbit part (25LC1024), also be sure to define USE_EEPROM_25LC1024 to enable the 24-bit device addressing used by that part. For external serial Flash, define MFPS_USE_SPI_FLASH instead of the EEPROM macros.

Images stored externally are uploaded via HTTP. This can be accomplished using the MPFS2 Utility, or can be accessed directly from a browser. Uploading files directly is described in the MPFS2 Utility documentation. Uploading images via HTTP can be accomplished as described in the Getting Started section.

When storing images externally, space can be reserved for separate application use. The configuration macro MPFS_RESERVE_BLOCK controls the size of this space. The specified number of bytes will be reserved at the beginning address of the storage device (0x000000). When using serial Flash, this address must be a multiple of the flash sector size (4096 bytes).

Using Internal Flash Storage

When storing images in internal Flash program memory, new images cannot be uploaded at run time. Instead, the image is compiled in as part of your project in the MPLAB IDE. To select this storage option comment out the configuration macro MPFS_USE_EEPROM in TCPIPConfig.h, then ensure that the image file generated by the MPFS2 Utility is included in the MPLAB project.

Other Considerations

MPFS2 defines a fixed number of files that can be opened simultaneously. The configuration parameter MAX_MPFS_HANDLES controls how many files can be opened at once. If this resource is depleted, no new files can be opened until MPFSClose is called for an existing handle. The HTTP2 web server expects to be able to use at least two handles for each connection, plus one extra. Additional handles should be allocated if other modules will be accessing the file system as well.

Topics
Name | Description
MPFS2 Public Members | Functions and variables accessible by the stack application
MPFS2 Stack Members | Functions and variables intended to be accessed only by the stack
MPFS2 Internal Members | Functions and variables internal to the MPFS2 module
Stack API > MPFS2


MPFS2 Public Members

Contents | Index | Home
Previous | Up | Next
MPFS2 Public Members

The following functions and variables are accessible by the stack application.

Enumerations
Name | Description
MPFS_SEEK_MODE | Indicates the method for MPFSSeek
Functions
Name | Description
MPFSClose | Closes a file.
MPFSFormat | Prepares the MPFS image for writing.
MPFSGet | Reads a byte from a file.
MPFSGetArray | Reads a series of bytes from a file.
MPFSGetBytesRem | Determines how many bytes remain to be read.
MPFSGetEndAddr | Determines the ending address of a file.
MPFSGetFilename | Reads the file name of a file that is already open.
MPFSGetFlags | Reads a file's flags.
MPFSGetID | Determines the ID in the FAT for a file.
MPFSGetLong | Reads a DWORD or Long value from the MPFS.
MPFSGetMicrotime | Reads the microtime portion of a file's timestamp.
MPFSGetPosition | Determines the current position in the file
MPFSGetSize | Reads the size of a file.
MPFSGetStartAddr | Reads the starting address of a file.
MPFSGetTimestamp | Reads the timestamp for the specified file.
MPFSOpen | Opens a file in the MPFS2 file system.
MPFSOpenID | Quickly re-opens a file.
MPFSOpenROM | Opens a file in the MPFS2 file system.
MPFSPutArray | Writes an array of data to the MPFS image.
MPFSSeek | Moves the current read pointer to a new location.
MPFSPutEnd | Finalizes an MPFS writing operation.
Macros
Name | Description
MPFS_INVALID | Indicates a position pointer is invalid
MPFS_INVALID_HANDLE | Indicates that a handle is not valid
Module

MPFS2

Types
Name | Description
MPFS_HANDLE | MPFS Handles are currently stored as BYTEs
Stack API > MPFS2 > Public Members


MPFS_HANDLE Type

Contents | Index | Home
Previous | Up | Next
MPFS_HANDLE Type
C
typedef BYTE MPFS_HANDLE;
Description

MPFS Handles are currently stored as BYTEs

Stack API > MPFS2 > Public Members > MPFS_HANDLE Type


MPFS_INVALID Macro

Contents | Index | Home
Previous | Up | Next
MPFS_INVALID Macro
C
#define MPFS_INVALID (0xffffffffu)    // Indicates a position pointer is invalid
Description

Indicates a position pointer is invalid

Stack API > MPFS2 > Public Members > MPFS_INVALID Macro


MPFS_INVALID_HANDLE Macro

Contents | Index | Home
Previous | Up | Next
MPFS_INVALID_HANDLE Macro
C
#define MPFS_INVALID_HANDLE (0xffu)            // Indicates that a handle is not valid
Description

Indicates that a handle is not valid

Stack API > MPFS2 > Public Members > MPFS_INVALID_HANDLE Macro


MPFS_SEEK_MODE Enumeration

Contents | Index | Home
Previous | Up | Next
MPFS_SEEK_MODE Enumeration
C
typedef enum {
  MPFS_SEEK_START = 0u,
  MPFS_SEEK_END,
  MPFS_SEEK_FORWARD,
  MPFS_SEEK_REWIND
} MPFS_SEEK_MODE;
Description

Indicates the method for MPFSSeek

Members
Members | Description
MPFS_SEEK_START = 0u | Seek forwards from the front of the file
MPFS_SEEK_END | Seek backwards from the end of the file
MPFS_SEEK_FORWARD | Seek forward from the current position
MPFS_SEEK_REWIND | See backwards from the current position
Stack API > MPFS2 > Public Members > MPFS_SEEK_MODE Enumeration


MPFSClose Function

Contents | Index | Home
Previous | Up | Next
MPFSClose Function
C
void MPFSClose(
    MPFS_HANDLE hMPFS
);
Description

Closes a file and releases its stub back to the pool of available handles.

Preconditions

None

Parameters
Parameters | Description
hMPFS | the file handle to be closed
Returns

None

Stack API > MPFS2 > Public Members > MPFSClose Function


MPFSFormat Function

Contents | Index | Home
Previous | Up | Next
MPFSFormat Function
C
MPFS_HANDLE MPFSFormat();
Description

Prepares the MPFS image for writing and locks the image so that other processes may not access it.

Preconditions

None

Returns

An MPFS handle that can be used for MPFSPut commands, or MPFS_INVALID_HANDLE when the EEPROM failed to initialize for writing.

Remarks

In order to prevent misreads, the MPFS will be inaccessible until MPFSClose is called. This function is not available when the MPFS is stored in internal Flash program memory.

Stack API > MPFS2 > Public Members > MPFSFormat Function


MPFSGet Function

Contents | Index | Home
Previous | Up | Next
MPFSGet Function
C
BOOL MPFSGet(
    MPFS_HANDLE hMPFS,
    BYTE* c
);
Description

Reads a byte from a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read
c | Where to store the byte that was read
Return Values
Return Values | Description
TRUE | The byte was successfully read
FALSE | No byte was read because either the handle was invalid or the end of the file has been reached.
Stack API > MPFS2 > Public Members > MPFSGet Function


MPFSGetArray Function

Contents | Index | Home
Previous | Up | Next
MPFSGetArray Function
C
WORD MPFSGetArray(
    MPFS_HANDLE hMPFS,
    BYTE* cData,
    WORD wLen
);
Description

Reads a series of bytes from a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read
cData | where to store the bytes that were read
wLen | how many bytes to read
Returns

The number of bytes successfully read. If this is less than wLen, an EOF occurred while attempting to read.

Stack API > MPFS2 > Public Members > MPFSGetArray Function


MPFSGetBytesRem Function

Contents | Index | Home
Previous | Up | Next
MPFSGetBytesRem Function
C
DWORD MPFSGetBytesRem(
    MPFS_HANDLE hMPFS
);
Description

Determines how many bytes remain to be read.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read the metadata
Returns

The number of bytes remaining in the file as a DWORD

Stack API > MPFS2 > Public Members > MPFSGetBytesRem Function


MPFSGetEndAddr Function

Contents | Index | Home
Previous | Up | Next
MPFSGetEndAddr Function
C
MPFS_PTR MPFSGetEndAddr(
    MPFS_HANDLE hMPFS
);
Description

Determines the ending address of a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read the metadata
Returns

The address just after the file ends (start address of next file)

Stack API > MPFS2 > Public Members > MPFSGetEndAddr Function


MPFSGetFilename Function

Contents | Index | Home
Previous | Up | Next
MPFSGetFilename Function
C
BOOL MPFSGetFilename(
    MPFS_HANDLE hMPFS,
    BYTE* cName,
    WORD wLen
);
Description

Reads the file name of a file that is already open.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to determine the file name
cName | where to store the name of the file
wLen | the maximum length of data to store in cName
Return Values
Return Values | Description
TRUE | the file name was successfully located
FALSE | the file handle provided is not currently open
Stack API > MPFS2 > Public Members > MPFSGetFilename Function


MPFSGetFlags Function

Contents | Index | Home
Previous | Up | Next
MPFSGetFlags Function
C
WORD MPFSGetFlags(
    MPFS_HANDLE hMPFS
);
Description

Reads a file's flags.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read the metadata
Returns

The flags that were associated with the file

Stack API > MPFS2 > Public Members > MPFSGetFlags Function


MPFSGetID Function

Contents | Index | Home
Previous | Up | Next
MPFSGetID Function
C
WORD MPFSGetID(
    MPFS_HANDLE hMPFS
);
Description

Determines the ID in the FAT for a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read the metadata
Returns

The ID in the FAT for this file

Remarks

Use this function in association with MPFSOpenID to quickly access file without permanently reserving a file handle.

Stack API > MPFS2 > Public Members > MPFSGetID Function


MPFSGetLong Function

Contents | Index | Home
Previous | Up | Next
MPFSGetLong Function
C
BOOL MPFSGetLong(
    MPFS_HANDLE hMPFS,
    DWORD* ul
);
Description

Reads a DWORD or Long value from the MPFS.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read
ul | where to store the DWORD or long value that was read
Returns

TRUE - The byte was successfully read FALSE - No byte was read because either the handle was invalid or the end of the file has been reached.

Stack API > MPFS2 > Public Members > MPFSGetLong Function


MPFSGetMicrotime Function

Contents | Index | Home
Previous | Up | Next
MPFSGetMicrotime Function
C
DWORD MPFSGetMicrotime(
    MPFS_HANDLE hMPFS
);
Description

Reads the microtime portion of a file's timestamp.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read the metadata
Returns

The microtime that was read as a DWORD

Stack API > MPFS2 > Public Members > MPFSGetMicrotime Function


MPFSGetPosition Function

Contents | Index | Home
Previous | Up | Next
MPFSGetPosition Function
C
DWORD MPFSGetPosition(
    MPFS_HANDLE hMPFS
);
Description

Determines the current position in the file

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle for which to determine position
Returns

The position in the file as a DWORD (or MPFS_PTR)

Remarks

Calling MPFSSeek(hMPFS, pos, MPFS_SEEK_START) will return the pointer to this position at a later time. (Where pos is the value returned by this function.)

Stack API > MPFS2 > Public Members > MPFSGetPosition Function


MPFSGetSize Function

Contents | Index | Home
Previous | Up | Next
MPFSGetSize Function
C
DWORD MPFSGetSize(
    MPFS_HANDLE hMPFS
);
Description

Reads the size of a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read the metadata
Returns

The size that was read as a DWORD

Stack API > MPFS2 > Public Members > MPFSGetSize Function


MPFSGetStartAddr Function

Contents | Index | Home
Previous | Up | Next
MPFSGetStartAddr Function
C
MPFS_PTR MPFSGetStartAddr(
    MPFS_HANDLE hMPFS
);
Description

Reads the starting address of a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read the metadata
Returns

The starting address of the file in the MPFS image

Stack API > MPFS2 > Public Members > MPFSGetStartAddr Function


MPFSGetTimestamp Function

Contents | Index | Home
Previous | Up | Next
MPFSGetTimestamp Function
C
DWORD MPFSGetTimestamp(
    MPFS_HANDLE hMPFS
);
Description

Reads the timestamp for the specified file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle from which to read the metadata
Returns

The timestamp that was read as a DWORD

Stack API > MPFS2 > Public Members > MPFSGetTimestamp Function


MPFSOpen Function

Contents | Index | Home
Previous | Up | Next
MPFSOpen Function
C
MPFS_HANDLE MPFSOpen(
    BYTE* cFile
);
Description

Opens a file in the MPFS2 file system.

Preconditions

None

Parameters
Parameters | Description
cFile | a null terminated file name to open
Returns

An MPFS_HANDLE to the opened file if found, or MPFS_INVALID_HANDLE if the file could not be found or no free handles exist.

Stack API > MPFS2 > Public Members > MPFSOpen Function


MPFSOpenID Function

Contents | Index | Home
Previous | Up | Next
MPFSOpenID Function
C
MPFS_HANDLE MPFSOpenID(
    WORD hFatID
);
Description

Quickly re-opens a file in the MPFS2 file system. Use this function along with MPFSGetID() to quickly re-open a file without tying up a permanent MPFSStub.

Preconditions

None

Parameters
Parameters | Description
hFatID | the ID of a previous opened file in the FAT
Returns

An MPFS_HANDLE to the opened file if found, or MPFS_INVALID_HANDLE if the file could not be found or no free handles exist.

Stack API > MPFS2 > Public Members > MPFSOpenID Function


MPFSOpenROM Function

Contents | Index | Home
Previous | Up | Next
MPFSOpenROM Function
C
MPFS_HANDLE MPFSOpenROM(
    ROM BYTE* cFile
);
Description

Opens a file in the MPFS2 file system.

Preconditions

None

Parameters
Parameters | Description
cFile | a null terminated file name to open
Returns

An MPFS_HANDLE to the opened file if found, or MPFS_INVALID_HANDLE if the file could not be found or no free handles exist.

Remarks

This function is aliased to MPFSOpen on non-PIC18 platforms.

Stack API > MPFS2 > Public Members > MPFSOpenROM Function


MPFSPutArray Function

Contents | Index | Home
Previous | Up | Next
MPFSPutArray Function
C
WORD MPFSPutArray(
    MPFS_HANDLE hMPFS,
    BYTE* cData,
    WORD wLen
);
Description

Writes an array of data to the MPFS image.

Preconditions

MPFSFormat was sucessfully called.

Parameters
Parameters | Description
hMPFS | the file handle for writing
cData | the array of bytes to write
wLen | how many bytes to write
Returns

The number of bytes successfully written.

Remarks

For EEPROM, the actual write may not initialize until the internal write page is full. To ensure that previously written data gets stored, MPFSPutEnd must be called after the last call to MPFSPutArray.

Stack API > MPFS2 > Public Members > MPFSPutArray Function


MPFSSeek Function

Contents | Index | Home
Previous | Up | Next
MPFSSeek Function
C
BOOL MPFSSeek(
    MPFS_HANDLE hMPFS,
    DWORD dwOffset,
    MPFS_SEEK_MODE tMode
);
Description

Moves the current read pointer to a new location.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters
Parameters | Description
hMPFS | the file handle to seek with
dwOffset | offset from the specified position in the specified direction
tMode | one of the MPFS_SEEK_MODE constants
Returns

TRUE - the seek was successful FALSE - either the new location or the handle itself was invalid

Stack API > MPFS2 > Public Members > MPFSSeek Function


MPFSPutEnd Function

Contents | Index | Home
Previous | Up | Next
MPFSPutEnd Function
C
void MPFSPutEnd(
    BOOL final
);
Description

Finalizes an MPFS writing operation.

Preconditions

MPFSFormat and MPFSPutArray were sucessfully called.

Parameters
Parameters | Description
final | TRUE if the application is done writing, FALSE if MPFS2 called this function locally.
Returns

None

Stack API > MPFS2 > Public Members > MPFSPutEnd Function


MPFS2 Stack Members

Contents | Index | Home
Previous | Up | Next
MPFS2 Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
MPFSInit | Initializes the MPFS module.
Module

MPFS2

Stack API > MPFS2 > Stack Members


MPFSInit Function

Contents | Index | Home
Previous | Up | Next
MPFSInit Function
C
void MPFSInit();
Description

Sets all MPFS handles to closed, and initializes access to the EEPROM if necessary.

Preconditions

None

Returns

None

Remarks

This function is called only one during lifetime of the application.

Stack API > MPFS2 > Stack Members > MPFSInit Function


MPFS2 Internal Members

Contents | Index | Home
Previous | Up | Next
MPFS2 Internal Members

The following functions and variables are designated as internal to the MPFS2 module.

Functions
Name | Description
ReadProgramMemory | Assembly function to read all three bytes of program memory for 16-bit parts
_LoadFATRecord | Loads the FAT record for a specified handle.
_Validate | Validates the MPFS Image
Macros
Name | Description
MAX_FILE_NAME_LEN | Supports long file names to 64 characters
MPFS_WRITE_PAGE_SIZE | Defines the size of a page in EEPROM
MPFS2_FLAG_HASINDEX | Indicates a file has an associated index of dynamic variables
MPFS2_FLAG_ISZIPPED | Indicates a file is compressed with GZIP compression
MPFSTell | Alias of MPFSGetPosition
MPFS_INVALID_FAT | Indicates an invalid FAT cache
Module

MPFS2

Structures
Name | Description
MPFS_STUB | Stores each file handle's information Handles are free when addr = MPFS_INVALID
MPFS_FAT_RECORD | Stores the data for an MPFS2 FAT record
Types
Name | Description
MPFS_PTR | MPFS Pointers are currently DWORDs
Variables
Name | Description
isMPFSLocked | Allows the MPFS to be locked, preventing access during updates
lastRead | Track the last read address to prevent unnecessary data overhead to switch locations.
MPFSStubs | Track the MPFS File Handles MPFSStubs[0] is reserved for internal use (FAT access)
fatCache | FAT record cache
fatCacheID | ID of currently loaded fatCache
numFiles | Number of files in this MPFS image
Stack API > MPFS2 > Internal Members


isMPFSLocked Variable

Contents | Index | Home
Previous | Up | Next
isMPFSLocked Variable
C
BOOL isMPFSLocked;
Description

Allows the MPFS to be locked, preventing access during updates

Stack API > MPFS2 > Internal Members > isMPFSLocked Variable


lastRead Variable

Contents | Index | Home
Previous | Up | Next
lastRead Variable
C
MPFS_PTR lastRead;
Description

Track the last read address to prevent unnecessary data overhead to switch locations.

Stack API > MPFS2 > Internal Members > lastRead Variable


MAX_FILE_NAME_LEN Macro

Contents | Index | Home
Previous | Up | Next
MAX_FILE_NAME_LEN Macro
C
#define MAX_FILE_NAME_LEN (64u)
Description

Supports long file names to 64 characters

Stack API > MPFS2 > Internal Members > MAX_FILE_NAME_LEN Macro


MPFS_PTR Type

Contents | Index | Home
Previous | Up | Next
MPFS_PTR Type
C
typedef DWORD MPFS_PTR;
Description

MPFS Pointers are currently DWORDs

Stack API > MPFS2 > Internal Members > MPFS_PTR Type


MPFS_STUB Structure

Contents | Index | Home
Previous | Up | Next
MPFS_STUB Structure
C
typedef struct {
  MPFS_PTR addr;
  DWORD bytesRem;
  WORD fatID;
} MPFS_STUB;
Description

Stores each file handle's information Handles are free when addr = MPFS_INVALID

Members
Members | Description
MPFS_PTR addr; | Current address in the file system
DWORD bytesRem; | How many bytes remain in this file
WORD fatID; | ID of which file in the FAT was accessed
Stack API > MPFS2 > Internal Members > MPFS_STUB Structure


MPFS_WRITE_PAGE_SIZE Macro

Contents | Index | Home
Previous | Up | Next
MPFS_WRITE_PAGE_SIZE Macro
C
#define MPFS_WRITE_PAGE_SIZE (64u)    // Defines the size of a page in EEPROM
Description

Defines the size of a page in EEPROM

Stack API > MPFS2 > Internal Members > MPFS_WRITE_PAGE_SIZE Macro


MPFS2_FLAG_HASINDEX Macro

Contents | Index | Home
Previous | Up | Next
MPFS2_FLAG_HASINDEX Macro
C
#define MPFS2_FLAG_HASINDEX ((WORD)0x0002)    // Indicates a file has an associated index of dynamic variables
Description

Indicates a file has an associated index of dynamic variables

Stack API > MPFS2 > Internal Members > MPFS2_FLAG_HASINDEX Macro


MPFS2_FLAG_ISZIPPED Macro

Contents | Index | Home
Previous | Up | Next
MPFS2_FLAG_ISZIPPED Macro
C
#define MPFS2_FLAG_ISZIPPED ((WORD)0x0001)    // Indicates a file is compressed with GZIP compression
Description

Indicates a file is compressed with GZIP compression

Stack API > MPFS2 > Internal Members > MPFS2_FLAG_ISZIPPED Macro


MPFSStubs Variable

Contents | Index | Home
Previous | Up | Next
MPFSStubs Variable
C
MPFS_STUB MPFSStubs[MAX_MPFS_HANDLES+1];
Description

Track the MPFS File Handles MPFSStubs[0] is reserved for internal use (FAT access)

Stack API > MPFS2 > Internal Members > MPFSStubs Variable


MPFSTell Macro

Contents | Index | Home
Previous | Up | Next
MPFSTell Macro
C
#define MPFSTell(a) MPFSGetPosition(a)
Description

Alias of MPFSGetPosition

Stack API > MPFS2 > Internal Members > MPFSTell Macro


ReadProgramMemory Function

Contents | Index | Home
Previous | Up | Next
ReadProgramMemory Function
C
DWORD ReadProgramMemory(
    DWORD address
);
Description

Assembly function to read all three bytes of program memory for 16-bit parts

Stack API > MPFS2 > Internal Members > ReadProgramMemory Function


_LoadFATRecord Function

Contents | Index | Home
Previous | Up | Next
_LoadFATRecord Function
C
static void _LoadFATRecord(
    WORD fatID
);
Description

Loads the FAT record for a specified handle.

Preconditions

None

Parameters
Parameters | Description
fatID | the ID of the file whose FAT is to be loaded
Returns

None

Remarks

The FAT record will be stored in fatCache.

Stack API > MPFS2 > Internal Members > _LoadFATRecord Function


_Validate Function

Contents | Index | Home
Previous | Up | Next
_Validate Function
C
static void _Validate();
Description

Verifies that the MPFS image is valid, and reads the number of available files from the image header. This function is called on boot, and again after any image is written.

Preconditions

None

Returns

None

Stack API > MPFS2 > Internal Members > _Validate Function


MPFS_FAT_RECORD Structure

Contents | Index | Home
Previous | Up | Next
MPFS_FAT_RECORD Structure
C
typedef struct {
  DWORD string;
  DWORD data;
  DWORD len;
  DWORD timestamp;
  DWORD microtime;
  WORD flags;
} MPFS_FAT_RECORD;
Description

Stores the data for an MPFS2 FAT record

Members
Members | Description
DWORD string; | Pointer to the file name
DWORD data; | Address of the file data
DWORD len; | Length of file data
DWORD timestamp; | Timestamp of file
DWORD microtime; | Microtime stamp of file
WORD flags; | Flags for this file
Stack API > MPFS2 > Internal Members > MPFS_FAT_RECORD Structure


fatCache Variable

Contents | Index | Home
Previous | Up | Next
fatCache Variable
C
MPFS_FAT_RECORD fatCache;
Description

FAT record cache

Stack API > MPFS2 > Internal Members > fatCache Variable


fatCacheID Variable

Contents | Index | Home
Previous | Up | Next
fatCacheID Variable
C
WORD fatCacheID;
Description

ID of currently loaded fatCache

Stack API > MPFS2 > Internal Members > fatCacheID Variable


numFiles Variable

Contents | Index | Home
Previous | Up | Next
numFiles Variable
C
WORD numFiles;
Description

Number of files in this MPFS image

Stack API > MPFS2 > Internal Members > numFiles Variable


MPFS_INVALID_FAT Macro

Contents | Index | Home
Previous | Up | Next
MPFS_INVALID_FAT Macro
C
#define MPFS_INVALID_FAT (0xffffu)        // Indicates an invalid FAT cache
Description

Indicates an invalid FAT cache

Stack API > MPFS2 > Internal Members > MPFS_INVALID_FAT Macro


NBNS

Contents | Index | Home
Previous | Up | Next
NBNS

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 "TCPIP 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.

Topics
Name | Description
NBNS Stack Members | Functions and variables intended to be accessed only by the stack.
Stack API > NBNS


NBNS Stack Members

Contents | Index | Home
Previous | Up | Next
NBNS Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
NBNSGetName | Reads the NetBIOS name from a UDP socket and copies it into a user-specified buffer.
NBNSPutName | Transmits the NetBIOS name across an open UDP socket.
NBNSTask | Sends responses to NetBIOS name requests
Macros
Name | Description
NBNS_PORT | NetBIOS Name Service port
Module

NBNS

Structures
Name | Description
NBNS_HEADER | NBNS Header structure
_NBNS_HEADER | NBNS Header structure
Stack API > NBNS > Stack Members


NBNSGetName Function

Contents | Index | Home
Previous | Up | Next
NBNSGetName Function
C
static void NBNSGetName(
    BYTE * String
);
Description

Reads the NetBIOS name from a UDP socket and copies it into a user-specified buffer.

Preconditions

None

Parameters
Parameters | Description
String | Pointer to an array into which a received NetBIOS name should be copied.
Returns

None

Side Effects

None

Remarks

None

Stack API > NBNS > Stack Members > NBNSGetName Function


NBNSPutName Function

Contents | Index | Home
Previous | Up | Next
NBNSPutName Function
C
static void NBNSPutName(
    BYTE * String
);
Description

Transmits the NetBIOS name across an open UDP socket.

Preconditions

None

Parameters
Parameters | Description
String | The name to transmit
Returns

None

Side Effects

None

Remarks

None

Stack API > NBNS > Stack Members > NBNSPutName Function


NBNSTask Function

Contents | Index | Home
Previous | Up | Next
NBNSTask Function
C
void NBNSTask();
Description

Sends responses to NetBIOS name requests

Preconditions

None

Returns

None

Side Effects

None

Remarks

None

Stack API > NBNS > Stack Members > NBNSTask Function


NBNS_HEADER Structure

Contents | Index | Home
Previous | Up | Next
NBNS_HEADER Structure
C
typedef struct _NBNS_HEADER {
  WORD_VAL TransactionID;
  WORD_VAL Flags;
  WORD_VAL Questions;
  WORD_VAL Answers;
  WORD_VAL AuthoritativeRecords;
  WORD_VAL AdditionalRecords;
} NBNS_HEADER;
Description

NBNS Header structure

Stack API > NBNS > Stack Members > NBNS_HEADER Structure


NBNS_PORT Macro

Contents | Index | Home
Previous | Up | Next
NBNS_PORT Macro
C
#define NBNS_PORT (137u)
Description

NetBIOS Name Service port

Stack API > NBNS > Stack Members > NBNS_PORT Macro


Performance Tests

Contents | Index | Home
Previous | Up | Next
Performance Tests

The TCP and UDP Performance Test modules provide a method for obtaining metrics about the stack's performance. They can be used to benchmark the stack on various hardware platforms, and are also useful to determine how your custom application has affected stack performance.

The stack automatically calls these modules when they are included, so you never need to call any functions directly. Instructions for use of the modules can be found in the documentation for UDPPerformanceTask, TCPTXPerformanceTask, and TCPRXPerformanceTask.

Topics
Name | Description
Performance Test Stack Members | Functions and variables intended to be accessed only by the stack
Performance Test Internal Members | Functions and variables internal to the module
Stack API > Performance Tests


Performance Test Stack Members

Contents | Index | Home
Previous | Up | Next
Performance Test Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
TCPPerformanceTask | Tests the performance of the TCP module.
UDPPerformanceTask | Tests the transmit performance of the UDP module.
Module

Performance Tests

Stack API > Performance Tests > Stack Members


TCPPerformanceTask Function

Contents | Index | Home
Previous | Up | Next
TCPPerformanceTask Function
C
void TCPPerformanceTask();
Description

This function calls both TCPTXPerformanceTask and TCPRXPerformanceTask to perform the performance task functions. Refer to the documentation for each of those functions for details.

Preconditions

TCP is initialized.

Returns

None

Stack API > Performance Tests > Stack Members > TCPPerformanceTask Function


UDPPerformanceTask Function

Contents | Index | Home
Previous | Up | Next
UDPPerformanceTask Function
C
void UDPPerformanceTask();
Description

This function tests the transmit performance of the UDP module. At boot, this module will transmit 1024 large UDP broadcast packets of 1024 bytes each. Using a packet sniffer, one can determine how long this process takes and calculate the transmit rate of the stack. This function tests true UDP performance in that it will open a socket, transmit one packet, and close the socket for each loop. After this initial transmission, the module can be re-enabled by holding button 3.

This function is particularly useful after development to determine the impact of your application code on the stack's performance. A before and after comparison will indicate if your application is unacceptably blocking the processor or taking too long to execute.

Preconditions

UDP is initialized.

Returns

None

Stack API > Performance Tests > Stack Members > UDPPerformanceTask Function


Performance Test Internal Members

Contents | Index | Home
Previous | Up | Next
Performance Test Internal Members

The following functions and variables are designated as internal to the module.

Functions
Name | Description
TCPRXPerformanceTask | Tests the receive performance of the TCP module.
TCPTXPerformanceTask | Tests the transmit performance of the TCP module.
Macros
Name | Description
PERFORMANCE_PORT | Which UDP port to broadcast from for the UDP tests
RX_PERFORMANCE_PORT | The TCP port to listen on for TCP receive tests
TX_PERFORMANCE_PORT | The TCP port to listen on for TCP transmit tests
Module

Performance Tests

Stack API > Performance Tests > Internal Members


TCPRXPerformanceTask Function

Contents | Index | Home
Previous | Up | Next
TCPRXPerformanceTask Function
C
void TCPRXPerformanceTask();
Description

This function tests the receive performance of the TCP module. To use, open a telnet connection to the device on RX_PERFORMANCE_PORT (9763 by default). Then use your telnet utility to upload a large file to the device. Each second the board will report back how many bytes were received in the previous second.

TCP performance is affected by many factors, including round-trip time and the TCP buffer size. For faster results, increase the size of the RX buffer size for the TCP_PURPOSE_TCP_PERFORMANCE_RX socket in TCPIPConfig.h. Round-trip time is affected by the distance to the device, so across the desk will be orders of magnitude faster than across the Internet.

This function is particularly useful after development to determine the impact of your application code on the stack's performance. A before and after comparison will indicate if your application is unacceptably blocking the processor or taking too long to execute.

Preconditions

TCP is initialized.

Returns

None

Stack API > Performance Tests > Internal Members > TCPRXPerformanceTask Function


TCPTXPerformanceTask Function

Contents | Index | Home
Previous | Up | Next
TCPTXPerformanceTask Function
C
void TCPTXPerformanceTask();
Description

This function tests the transmit performance of the TCP module. To use, open a telnet connection to the device on TX_PERFORMANCE_PORT (9762 by default). The board will rapidly transmit data and report its performance to the telnet client.

TCP performance is affected by many factors, including round-trip time and the TCP buffer size. For faster results, increase the size of the TX buffer size for the TCP_PURPOSE_TCP_PERFORMANCE_TX socket in TCPIPConfig.h. Round-trip time is affected by the distance to the device, so across the desk will be orders of magnitude faster than across the Internet.

This function is particularly useful after development to determine the impact of your application code on the stack's performance. A before and after comparison will indicate if your application is unacceptably blocking the processor or taking too long to execute.

Preconditions

TCP is initialized.

Returns

None

Stack API > Performance Tests > Internal Members > TCPTXPerformanceTask Function


PERFORMANCE_PORT Macro

Contents | Index | Home
Previous | Up | Next
PERFORMANCE_PORT Macro
C
#define PERFORMANCE_PORT 9
Description

Which UDP port to broadcast from for the UDP tests

Stack API > Performance Tests > Internal Members > PERFORMANCE_PORT Macro


RX_PERFORMANCE_PORT Macro

Contents | Index | Home
Previous | Up | Next
RX_PERFORMANCE_PORT Macro
C
#define RX_PERFORMANCE_PORT 9763
Description

The TCP port to listen on for TCP receive tests

Stack API > Performance Tests > Internal Members > RX_PERFORMANCE_PORT Macro


TX_PERFORMANCE_PORT Macro

Contents | Index | Home
Previous | Up | Next
TX_PERFORMANCE_PORT Macro
C
#define TX_PERFORMANCE_PORT 9762
Description

The TCP port to listen on for TCP transmit tests

Stack API > Performance Tests > Internal Members > TX_PERFORMANCE_PORT Macro


SMTP Client

Contents | Index | Home
Previous | Up | Next
SMTP Client

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 ISP or network administrator can provide the correct address, but end-user applications will need an interface to provide this data.

Topics
Name | Description
SMTP Client Examples | Examples for using the SMTP Client
SMTP Client Public Members | Functions and variables accessible by the stack application
SMTP Client Stack Members | Functions and variables intended to be accessed only by the stack
SMTP Client Internal Members | Functions and variables used internally by the SMTP Client
Stack API > SMTP Client


SMTP Client Examples

Contents | Index | Home
Previous | Up | Next
SMTP Client Examples

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 is started by the stack, but the delivery of the contents happens in pieces and is handled by the application.

Module

SMTP Client

Topics
Name | Description
SMTP Client Short Message Example | Send a message whose contents can be read from memory
SMTP Client Long Message Example | Sends a long message built in pieces by the application
Stack API > SMTP Client > Examples


SMTP Client Short Message Example

Contents | Index | Home
Previous | Up | Next
SMTP Client Short Message Example

The SMTP client API is simplified when messages can be buffered entirely in RAM. The SMTPDemo 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 diagram below provides an overview of the process:

First, call SMTPBeginUsage 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 to instruct the SMTP client to begin transmission.

The application must now call SMTPIsBusy 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 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 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 processed, and will extinguish when the SMTP state machine completes. If the transmission was successful LED2 will light, otherwise it will remain dark.

Stack API > SMTP Client > Examples > Short Message


SMTP Client Long Message Example

Contents | Index | Home
Previous | Up | Next
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 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 diagram below illustrates the first stage:

The first stage is largely similar to the first few steps in sending a short message. First, call SMTPBeginUsage 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 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:

Upon entering stage two, the application should call SMTPIsBusy to verify that the connection to the remote server is active and has not been lost. If the call succeeds, call SMTPIsPutReady 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, SMTPPutArray, SMTPPutROMArray, SMTPPutString, and SMTPPutROMString 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 to track how much free space remains in the TX buffer. Once the buffer is depleted, call SMTPFlush to force the data written to be sent.

The SMTP client module can accept 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 to inform the SMTP client that no more data remains. Then call SMTPIsBusy 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 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, and ensure that these fields are being properly assigned to SMTPClient 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.

Stack API > SMTP Client > Examples > Long Message


SMTP Client Public Members

Contents | Index | Home
Previous | Up | Next
SMTP Client Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
SMTPBeginUsage | Requests control of the SMTP client module.
SMTPEndUsage | Releases control of the SMTP client module.
SMTPFlush | Flushes the SMTP socket and forces all data to be sent.
SMTPIsBusy | Determines if the SMTP client is busy.
SMTPIsPutReady | Determines how much data can be written to the SMTP client.
SMTPPut | Writes a single byte to the SMTP client.
SMTPPutArray | Writes a series of bytes to the SMTP client.
SMTPPutDone | Indicates that the on-the-fly message is complete.
SMTPPutROMArray | Writes a series of bytes from ROM to the SMTP client.
SMTPPutROMString | Writes a string from ROM to the SMTP client.
SMTPPutString | Writes a string to the SMTP client.
SMTPSendMail | Initializes the message sending process.
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
Module

SMTP Client

Structures
Name | Description
SMTP_POINTERS | Configures the SMTP client to send a message
Variables
Name | Description
SMTPClient |
Stack API > SMTP Client > Public Members


SMTP_CONNECT_ERROR Macro

Contents | Index | Home
Previous | Up | Next
SMTP_CONNECT_ERROR Macro
C
#define SMTP_CONNECT_ERROR (0x8001u)    // Connection to SMTP server failed
Description

Connection to SMTP server failed

Stack API > SMTP Client > Public Members > SMTP_CONNECT_ERROR Macro


SMTP_POINTERS Structure

Contents | Index | Home
Previous | Up | Next
SMTP_POINTERS Structure
C
typedef struct {
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } Server;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } Username;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } Password;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } To;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } CC;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } BCC;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } From;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } Subject;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } OtherHeaders;
  union {
    BYTE * szRAM;
    ROM BYTE * szROM;
  } Body;
  struct {
    unsigned char Server : 1;
    unsigned char Username : 1;
    unsigned char Password : 1;
    unsigned char To : 1;
    unsigned char CC : 1;
    unsigned char BCC : 1;
    unsigned char From : 1;
    unsigned char Subject : 1;
    unsigned char OtherHeaders : 1;
    unsigned char Body : 1;
  } ROMPointers;
  BOOL UseSSL;
  WORD ServerPort;
} SMTP_POINTERS;
Description

This structure of pointers configures the SMTP Client to send an e-mail message. Initially, all pointers will be null. Set SMTPClient.[field name].szRAM to use a string stored in RAM, or SMTPClient.[field name].szROM to use a string stored in ROM. (Where [field name] is one of the parameters below.)

If a ROM string is specified, SMTPClient.ROMPointers.[field name] must also be set to 1 to indicate that this field should be retrieved from ROM instead of RAM.

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.
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.
ROMPointers | Indicates which parameters to read from ROM instead of RAM.
UseSSL | When STACK_USE_SSL_CLIENT is enabled, this flag causes the SMTP client to make an SSL connection to the server.
ServerPort | (WORD 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" <john.smith@domain.com>

Stack API > SMTP Client > Public Members > SMTP_POINTERS Structure


SMTP_RESOLVE_ERROR Macro

Contents | Index | Home
Previous | Up | Next
SMTP_RESOLVE_ERROR Macro
C
#define SMTP_RESOLVE_ERROR (0x8000u)    // DNS lookup for SMTP server failed
Description

DNS lookup for SMTP server failed

Stack API > SMTP Client > Public Members > SMTP_RESOLVE_ERROR Macro


SMTP_SUCCESS Macro

Contents | Index | Home
Previous | Up | Next
SMTP_SUCCESS Macro
C
#define SMTP_SUCCESS (0x0000u)    // Message was successfully sent
Description

Message was successfully sent

Stack API > SMTP Client > Public Members > SMTP_SUCCESS Macro


SMTPBeginUsage Function

Contents | Index | Home
Previous | Up | Next
SMTPBeginUsage Function
C
BOOL SMTPBeginUsage();
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 SMTPEndUsage 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 SMTPBeginUsage again later, after returning to the main program loop
Stack API > SMTP Client > Public Members > SMTPBeginUsage Function


SMTPClient Variable

Contents | Index | Home
Previous | Up | Next
SMTPClient Variable
C
SMTP_POINTERS SMTPClient;
Stack API > SMTP Client > Public Members > SMTPClient Variable


SMTPEndUsage Function

Contents | Index | Home
Previous | Up | Next
SMTPEndUsage Function
C
WORD SMTPEndUsage();
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 SMTPBeginUsage, and frees the SMTP client to be used by another application.

Preconditions

SMTPBeginUsage 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
Stack API > SMTP Client > Public Members > SMTPEndUsage Function


SMTPFlush Function

Contents | Index | Home
Previous | Up | Next
SMTPFlush Function
C
void SMTPFlush();
Description

Flushes the SMTP socket and forces all data to be sent.

Preconditions

SMTPBeginUsage 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, SMTPSendMail was called with SMTPClient.Body set to NULL.)

Stack API > SMTP Client > Public Members > SMTPFlush Function


SMTPIsBusy Function

Contents | Index | Home
Previous | Up | Next
SMTPIsBusy Function
C
BOOL SMTPIsBusy();
Description

Call this function to determine if the SMTP client is busy performing background tasks. This function should be called after any call to SMTPSendMail, SMTPPutDone to determine if the stack has finished performing its internal tasks. It should also be called prior to any call to SMTPIsPutReady to verify that the SMTP client has not prematurely disconnected. When this function returns FALSE, the next call should be to SMTPEndUsage to release the module and obtain the status code for the operation.

Preconditions

SMTPBeginUsage 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.
Stack API > SMTP Client > Public Members > SMTPIsBusy Function


SMTPIsPutReady Function

Contents | Index | Home
Previous | Up | Next
SMTPIsPutReady Function
C
WORD SMTPIsPutReady();
Description

Use this function to determine how much data can be written to the SMTP client when generating an on-the-fly message.

Preconditions

SMTPBeginUsage returned TRUE on a previous call, and an on-the-fly message is being generated. This requires that SMTPSendMail 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, SMTPSendMail was called with SMTPClient.Body set to NULL.)

Stack API > SMTP Client > Public Members > SMTPIsPutReady Function


SMTPPut Function

Contents | Index | Home
Previous | Up | Next
SMTPPut Function
C
BOOL SMTPPut(
    BYTE c
);
Description

Writes a single byte to the SMTP client.

Preconditions

SMTPBeginUsage 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
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, SMTPSendMail was called with SMTPClient.Body set to NULL.)

Stack API > SMTP Client > Public Members > SMTPPut Function


SMTPPutArray Function

Contents | Index | Home
Previous | Up | Next
SMTPPutArray Function
C
WORD SMTPPutArray(
    BYTE* Data,
    WORD Len
);
Description

Writes a series of bytes to the SMTP client.

Preconditions

SMTPBeginUsage returned TRUE on a previous call.

Parameters
Parameters | Description
Data | The data to be written
Len | How many bytes should be written
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, SMTPSendMail was called with SMTPClient.Body set to NULL.)

Stack API > SMTP Client > Public Members > SMTPPutArray Function


SMTPPutDone Function

Contents | Index | Home
Previous | Up | Next
SMTPPutDone Function
C
void SMTPPutDone();
Description

Indicates that the on-the-fly message is complete.

Preconditions

SMTPBeginUsage returned TRUE on a previous call, and the SMTP client is generated an on-the-fly message. (That is, SMTPSendMail was called with SMTPClient.Body set to NULL.)

Returns

None

Stack API > SMTP Client > Public Members > SMTPPutDone Function


SMTPPutROMArray Function

Contents | Index | Home
Previous | Up | Next
SMTPPutROMArray Function
C
WORD SMTPPutROMArray(
    ROM BYTE* Data,
    WORD Len
);
Description

Writes a series of bytes from ROM to the SMTP client.

Preconditions

SMTPBeginUsage returned TRUE on a previous call.

Parameters
Parameters | Description
Data | The data to be written
Len | How many bytes should be written
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, SMTPSendMail was called with SMTPClient.Body set to NULL.)

This function is aliased to SMTPPutArray on non-PIC18 platforms.

Stack API > SMTP Client > Public Members > SMTPPutROMArray Function


SMTPPutROMString Function

Contents | Index | Home
Previous | Up | Next
SMTPPutROMString Function
C
WORD SMTPPutROMString(
    ROM BYTE* Data
);
Description

Writes a string from ROM to the SMTP client.

Preconditions

SMTPBeginUsage 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, SMTPSendMail was called with SMTPClient.Body set to NULL.)

This function is aliased to SMTPPutString on non-PIC18 platforms.

Stack API > SMTP Client > Public Members > SMTPPutROMString Function


SMTPPutString Function

Contents | Index | Home
Previous | Up | Next
SMTPPutString Function
C
WORD SMTPPutString(
    BYTE* Data
);
Description

Writes a string to the SMTP client.

Preconditions

SMTPBeginUsage 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, SMTPSendMail was called with SMTPClient.Body set to NULL.)

Stack API > SMTP Client > Public Members > SMTPPutString Function


SMTPSendMail Function

Contents | Index | Home
Previous | Up | Next
SMTPSendMail Function
C
void SMTPSendMail();
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

SMTPBeginUsage returned TRUE on a previous call.

Returns

None

Stack API > SMTP Client > Public Members > SMTPSendMail Function


SMTP Client Stack Members

Contents | Index | Home
Previous | Up | Next
SMTP Client Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
SMTPTask | Performs any pending SMTP client tasks
Module

SMTP Client

Stack API > SMTP Client > Stack Members


SMTPTask Function

Contents | Index | Home
Previous | Up | Next
SMTPTask Function
C
void SMTPTask();
Description

This function handles periodic tasks associated with the SMTP client, such as processing initial connections and command sequences.

Preconditions

None

Returns

None

Remarks

This function acts as a task (similar to one in an RTOS). It performs its task in a co-operative manner, and the main application must call this function repeatedly to ensure that all open or new connections are served in a timely fashion.

Stack API > SMTP Client > Stack Members > SMTPTask Function


SMTP Client Internal Members

Contents | Index | Home
Previous | Up | Next
SMTP Client Internal Members

The following functions and variables are designated for internal use by the SMTP Client module.

Functions
Name | Description
FindEmailAddress | Searches a string for an e-mail address.
FindROMEmailAddress | Searches a ROM string for an e-mail address.
Macros
Name | Description
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)
Module

SMTP Client

Variables
Name | Description
CRPeriod | State machine for the CR LF Period replacement Used by SMTPPut to transparently replace "rn." with "rn.."
MySocket | Socket currently in use by the SMTP client
PutHeadersState | State machine for writing the SMTP message headers
ResponseCode | Response code from server when an error exists
RXParserState | State machine for parsing incoming responses
SMTPFlags | Internal flags used by the SMTP Client
SMTPServer | IP address of the remote SMTP server
SMTPState | Message state machine for the SMTP Client
TransportState | State of the transport for the SMTP Client
Stack API > SMTP Client > Internal Members


CRPeriod Variable

Contents | Index | Home
Previous | Up | Next
CRPeriod Variable
C
union {
  BYTE * Pos;
  enum {
    CR_PERIOD_SEEK_CR = 0,
    CR_PERIOD_SEEK_LF,
    CR_PERIOD_SEEK_PERIOD,
    CR_PERIOD_NEED_INSERTION
  } State;
} CRPeriod;
Description

State machine for the CR LF Period replacement Used by SMTPPut to transparently replace "rn." with "rn.."

Members
Members | Description
CR_PERIOD_SEEK_CR = 0 | Idle state, waiting for 'r
CR_PERIOD_SEEK_LF | r" has been written, so check next byte for 'n
CR_PERIOD_SEEK_PERIOD | rn" has been written, so check next byte for '.
CR_PERIOD_NEED_INSERTION | "rn." has been written, so an additional '.' must be written before the next byte.
Stack API > SMTP Client > Internal Members > CRPeriod Variable


FindEmailAddress Function

Contents | Index | Home
Previous | Up | Next
FindEmailAddress Function
C
static BYTE * FindEmailAddress(
    BYTE * str,
    WORD * wLen
);
Description

This function locates an e-mail address in a string. It is used internally by the SMTP client to parse out the actual address from the From and To strings so that the MAIL FROM and RCPT TO commands can be sent to the SMTP server.

Preconditions

SMTPBeginUsage returned TRUE on a previous call.

Parameters
Parameters | Description
str | The string in which to search for an e-mail address
wLen | the length of str
Returns

A pointer to the e-mail address

Stack API > SMTP Client > Internal Members > FindEmailAddress Function


FindROMEmailAddress Function

Contents | Index | Home
Previous | Up | Next
FindROMEmailAddress Function
C
static ROM BYTE * FindROMEmailAddress(
    ROM BYTE * str,
    WORD * wLen
);
Description

This function locates an e-mail address in a string. It is used internally by the SMTP client to parse out the actual address from the From and To strings so that the MAIL FROM and RCPT TO commands can be sent to the SMTP server.

Preconditions

SMTPBeginUsage returned TRUE on a previous call.

Parameters
Parameters | Description
str | The ROM string in which to search for an e-mail address
wLen | the length of str
Returns

A pointer to the e-mail address

Stack API > SMTP Client > Internal Members > FindROMEmailAddress Function


MySocket Variable

Contents | Index | Home
Previous | Up | Next
MySocket Variable
C
TCP_SOCKET MySocket = INVALID_SOCKET;
Description

Socket currently in use by the SMTP client

Stack API > SMTP Client > Internal Members > MySocket Variable


PutHeadersState Variable

Contents | Index | Home
Previous | Up | Next
PutHeadersState Variable
C
enum {
  PUTHEADERS_FROM_INIT = 0,
  PUTHEADERS_FROM,
  PUTHEADERS_TO_INIT,
  PUTHEADERS_TO,
  PUTHEADERS_CC_INIT,
  PUTHEADERS_CC,
  PUTHEADERS_SUBJECT_INIT,
  PUTHEADERS_SUBJECT,
  PUTHEADERS_OTHER_INIT,
  PUTHEADERS_OTHER,
  PUTHEADERS_DONE
} PutHeadersState;
Description

State machine for writing the SMTP message headers

Members
Members | Description
PUTHEADERS_FROM_INIT = 0 | Preparing to send From header
PUTHEADERS_FROM | Sending From header
PUTHEADERS_TO_INIT | Preparing to send To header
PUTHEADERS_TO | Sending To header
PUTHEADERS_CC_INIT | Preparing to send CC header
PUTHEADERS_CC | Sending CC header
PUTHEADERS_SUBJECT_INIT | Preparing to send Subject header
PUTHEADERS_SUBJECT | Sending Subject header
PUTHEADERS_OTHER_INIT | Preparing to send additional headers
PUTHEADERS_OTHER | Sending additional headers
PUTHEADERS_DONE | Done writing all headers
Stack API > SMTP Client > Internal Members > PutHeadersState Variable


ResponseCode Variable

Contents | Index | Home
Previous | Up | Next
ResponseCode Variable
C
WORD ResponseCode;
Description

Response code from server when an error exists

Stack API > SMTP Client > Internal Members > ResponseCode Variable


RXParserState Variable

Contents | Index | Home
Previous | Up | Next
RXParserState Variable
C
enum {
  RX_BYTE_0 = 0,
  RX_BYTE_1,
  RX_BYTE_2,
  RX_BYTE_3,
  RX_SEEK_CR,
  RX_SEEK_LF
} RXParserState;
Description

State machine for parsing incoming responses

Stack API > SMTP Client > Internal Members > RXParserState Variable


SMTP_PORT Macro

Contents | Index | Home
Previous | Up | Next
SMTP_PORT Macro
C
#define SMTP_PORT 25                    // Default port to use when unspecified
Description

Default port to use when unspecified

Stack API > SMTP Client > Internal Members > SMTP_PORT Macro


SMTP_SERVER_REPLY_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
SMTP_SERVER_REPLY_TIMEOUT Macro
C
#define SMTP_SERVER_REPLY_TIMEOUT (TICK_SECOND*8)        // How long to wait before assuming the connection has been dropped (default 8 seconds)
Description

How long to wait before assuming the connection has been dropped (default 8 seconds)

Stack API > SMTP Client > Internal Members > SMTP_SERVER_REPLY_TIMEOUT Macro


SMTPFlags Variable

Contents | Index | Home
Previous | Up | Next
SMTPFlags Variable
C
union {
  BYTE Val;
  struct {
    unsigned char RXSkipResponse : 1;
    unsigned char SMTPInUse : 1;
    unsigned char SentSuccessfully : 1;
    unsigned char ReadyToStart : 1;
    unsigned char ReadyToFinish : 1;
    unsigned char ConnectedOnce : 1;
    unsigned char filler : 2;
  } bits;
} SMTPFlags;
Description

Internal flags used by the SMTP Client

Stack API > SMTP Client > Internal Members > SMTPFlags Variable


SMTPServer Variable

Contents | Index | Home
Previous | Up | Next
SMTPServer Variable
C
IP_ADDR SMTPServer;
Description

IP address of the remote SMTP server

Stack API > SMTP Client > Internal Members > SMTPServer Variable


SMTPState Variable

Contents | Index | Home
Previous | Up | Next
SMTPState Variable
C
enum {
  SMTP_HOME = 0,
  SMTP_HELO,
  SMTP_HELO_ACK,
  SMTP_AUTH_LOGIN,
  SMTP_AUTH_LOGIN_ACK,
  SMTP_AUTH_USERNAME,
  SMTP_AUTH_USERNAME_ACK,
  SMTP_AUTH_PASSWORD,
  SMTP_AUTH_PASSWORD_ACK,
  SMTP_MAILFROM,
  SMTP_MAILFROM_ACK,
  SMTP_RCPTTO_INIT,
  SMTP_RCPTTO,
  SMTP_RCPTTO_ACK,
  SMTP_RCPTTO_ISDONE,
  SMTP_RCPTTOCC_INIT,
  SMTP_RCPTTOCC,
  SMTP_RCPTTOCC_ACK,
  SMTP_RCPTTOCC_ISDONE,
  SMTP_RCPTTOBCC_INIT,
  SMTP_RCPTTOBCC,
  SMTP_RCPTTOBCC_ACK,
  SMTP_RCPTTOBCC_ISDONE,
  SMTP_DATA,
  SMTP_DATA_ACK,
  SMTP_DATA_HEADER,
  SMTP_DATA_BODY_INIT,
  SMTP_DATA_BODY,
  SMTP_DATA_BODY_ACK,
  SMTP_QUIT_INIT,
  SMTP_QUIT
} SMTPState;
Description

Message state machine for the SMTP Client

Members
Members | Description
SMTP_HOME = 0 | Idle start state for SMTP client (application is preparing message)
SMTP_HELO | HELO is being sent to server
SMTP_HELO_ACK | Received an ACK for the HELO
SMTP_AUTH_LOGIN | Requesting to log in
SMTP_AUTH_LOGIN_ACK | Log in request accepted
SMTP_AUTH_USERNAME | Sending user name
SMTP_AUTH_USERNAME_ACK | User name accepted
SMTP_AUTH_PASSWORD | Sending password
SMTP_AUTH_PASSWORD_ACK | Password was accepted
SMTP_MAILFROM | Sending inital MAIL FROM command
SMTP_MAILFROM_ACK | MAIL FROM was accepted
SMTP_RCPTTO_INIT | Preparing to send RCPT TO
SMTP_RCPTTO | Sending RCPT TO command
SMTP_RCPTTO_ACK | RCPT TO was accepted
SMTP_RCPTTO_ISDONE | Done sending RCPT TO commands
SMTP_RCPTTOCC_INIT | Preparing to send RCPT TO CC commands
SMTP_RCPTTOCC | Sending RCPT TO CC commands
SMTP_RCPTTOCC_ACK | RCPT TO CC was accepted
SMTP_RCPTTOCC_ISDONE | Done sending RCPT TO CC
SMTP_RCPTTOBCC_INIT | Preparing to send RCPT TO BCC commands
SMTP_RCPTTOBCC | Sending RCPT TO BCC commands
SMTP_RCPTTOBCC_ACK | RCPT TO BCC was accepted
SMTP_RCPTTOBCC_ISDONE | Done sending RCPT TO BCC
SMTP_DATA | Sending DATA command
SMTP_DATA_ACK | DATA command accpted
SMTP_DATA_HEADER | Sending message headers
SMTP_DATA_BODY_INIT | Preparing for message body
SMTP_DATA_BODY | Sending message body
SMTP_DATA_BODY_ACK | Message body accepted
SMTP_QUIT_INIT | Sending QUIT command
SMTP_QUIT | QUIT accepted, connection closing
Stack API > SMTP Client > Internal Members > SMTPState Variable


TransportState Variable

Contents | Index | Home
Previous | Up | Next
TransportState Variable
C
enum {
  TRANSPORT_HOME = 0,
  TRANSPORT_BEGIN,
  TRANSPORT_NAME_RESOLVE,
  TRANSPORT_OBTAIN_SOCKET,
  TRANSPORT_SECURING_SOCKET,
  TRANSPORT_SOCKET_OBTAINED,
  TRANSPORT_CLOSE
} TransportState;
Description

State of the transport for the SMTP Client

Members
Members | Description
TRANSPORT_HOME = 0 | Idle state
TRANSPORT_BEGIN | Preparing to make connection
TRANSPORT_NAME_RESOLVE | Resolving the SMTP server address
TRANSPORT_OBTAIN_SOCKET | Obtaining a socket for the SMTP connection
TRANSPORT_SECURING_SOCKET | Securing the socket for the SMTP over SSL connection
TRANSPORT_SOCKET_OBTAINED | SMTP connection successful
TRANSPORT_CLOSE | STMP socket is closed
Stack API > SMTP Client > Internal Members > TransportState Variable


Reboot

Contents | Index | Home
Previous | Up | Next
Reboot

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. The port can be configured in Reboot.c with the following macro:

#define REBOOT_PORT      69

For improved security, you can limit reboot capabilities to users on the same subnet by specifying the following macro in Reboot.c:

#define REBOOT_SAME_SUBNET_ONLY
Topics
Name | Description
Reboot Stack Members | Functions and variables intended to be accessed only by the stack
Stack API > Reboot


Reboot Stack Members

Contents | Index | Home
Previous | Up | Next
Reboot Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
RebootTask | Checks for incomming traffic on port 69. Resets the PIC if a 'R' is received.
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.
Module

Reboot

Stack API > Reboot > Stack Members


RebootTask Function

Contents | Index | Home
Previous | Up | Next
RebootTask Function
C
void RebootTask();
Description

Checks for incomming traffic on port 69. Resets the PIC if a 'R' is received.

Preconditions

Stack is initialized()

Returns

None

Side Effects

None

Remarks

This module is primarily for use with the Ethernet bootloader. By resetting, the Ethernet bootloader can take control for a second and let a firmware upgrade take place.

Stack API > Reboot > Stack Members > RebootTask Function


REBOOT_PORT Macro

Contents | Index | Home
Previous | Up | Next
REBOOT_PORT Macro
C
#define REBOOT_PORT 69    // UDP TFTP port
Description

UDP TFTP port

Stack API > Reboot > Stack Members > REBOOT_PORT Macro


REBOOT_SAME_SUBNET_ONLY Macro

Contents | Index | Home
Previous | Up | Next
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.

Stack API > Reboot > Stack Members > REBOOT_SAME_SUBNET_ONLY Macro


SNMP

Contents | Index | Home
Previous | Up | Next
SNMP
Functions | Macros | Types | Variables

Simple Network Management Protocol V2c (community) agent implementation of [image] RFC 3416.

Topics
Name | Description
SNMP Public Members | Functions and variables accessible by the stack application
SNMP Internal Members | Functions and variables internal to the SNMP module
SNMP Stack Members | Functions and variables intended to be accessed only by the stack
Functions | The following table lists functions in this documentation.
Types | The following table lists types in this documentation.
Variables | The following table lists variables in this documentation.
Macros | The following table lists macros in this documentation.
Functions
Name | Description
getSnmpV2GenTrapOid | Resolves generic trap code to generic trap OID.
ProcessGetBulkVar | This is function ProcessGetBulkVar.
ProcessGetNextVar | This is function ProcessGetNextVar.
ProcessGetVar | This is function ProcessGetVar.
ProcessSnmpv3MsgData | This is function ProcessSnmpv3MsgData.
SNMPGetExactIndex | To search for exact index node in case of a Sequence variable.
SNMPIdRecrdValidation | Used to Restrict the access dynamic and non dynamic OID string for A perticular SNMP Version.
SNMPIsValidSetLen | Validates the set variable data length to data type.
Snmpv3AESDecryptRxedScopedPdu | This is function Snmpv3AESDecryptRxedScopedPdu.
Snmpv3BufferPut | This is function Snmpv3BufferPut.
Snmpv3FormulateEngineID | This is function Snmpv3FormulateEngineID.
Snmpv3GetAuthEngineTime | This is function Snmpv3GetAuthEngineTime.
Snmpv3GetBufferData | This is function Snmpv3GetBufferData.
Snmpv3InitializeUserDataBase | This is function Snmpv3InitializeUserDataBase.
Snmpv3MsgProcessingModelProcessPDU | This is function Snmpv3MsgProcessingModelProcessPDU.
Snmpv3Notify | This is function Snmpv3Notify.
Snmpv3ScopedPduProcessing | This is function Snmpv3ScopedPduProcessing.
Snmpv3TrapScopedpdu | This is function Snmpv3TrapScopedpdu.
Snmpv3UserSecurityModelProcessPDU | This is function Snmpv3UserSecurityModelProcessPDU.
Snmpv3UsmAesEncryptDecryptInitVector | This is function Snmpv3UsmAesEncryptDecryptInitVector.
Snmpv3UsmOutMsgAuthenticationParam | This is function Snmpv3UsmOutMsgAuthenticationParam.
Snmpv3ValidateEngineId | This is function Snmpv3ValidateEngineId.
Snmpv3ValidateSecNameAndSecLvl | This is function Snmpv3ValidateSecNameAndSecLvl.
Snmpv3ValidateSecurityName | This is function Snmpv3ValidateSecurityName.
Macros
Name | Description
IS_SNMPV3_AUTH_STRUCTURE | This is macro IS_SNMPV3_AUTH_STRUCTURE.
REPORT_RESPONSE | This is macro REPORT_RESPONSE.
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_V3 | This is macro SNMP_V3.
Types
Name | Description
INOUT_SNMP_PDU | This is type INOUT_SNMP_PDU.
SNMPNONMIBRECDINFO | This is type SNMPNONMIBRECDINFO.
SNMPV3MSGDATA | SNMPv3
Variables
Name | Description
getZeroInstance | This variable is used for gext next request for zero instance
gSNMPv3ScopedPduDataPos | This is variable gSNMPv3ScopedPduDataPos.
gSNMPv3ScopedPduRequestBuf | This is variable gSNMPv3ScopedPduRequestBuf.
gSNMPv3ScopedPduResponseBuf | This is variable gSNMPv3ScopedPduResponseBuf.
msgSecrtyParamLenOffset | This is variable msgSecrtyParamLenOffset.
Stack API > SNMP


SNMP Public Members

Contents | Index | Home
Previous | Up | Next
SNMP Public Members

The following functions and variables are available to the stack application.

Enumerations
Name | Description
GENERIC_TRAP_NOTIFICATION_TYPE | This is type GENERIC_TRAP_NOTIFICATION_TYPE.
VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE | This is type VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE.
SNMP_ACTION | This is the list of SNMP action a remote NMS can perform. This inforamtion is passed to application via callback SNMPValidateCommunity(). Application should validate the action for given community string.
COMMUNITY_TYPE | This is type COMMUNITY_TYPE.
Functions
Name | Description
SNMPSendTrap | Prepare, validate remote node which will receive trap and send trap pdu.
SNMPValidateCommunity | This is function SNMPValidateCommunity.
SNMPNotify | Creates and Sends TRAP pdu.
SNMPSetVar | This routine Set the mib variable with the requested value.
SNMPGetVar | Used to Get/collect OID variable information.
SNMPIsNotifyReady | Resolves given remoteHost IP address into MAC address.
SNMPNotifyPrepare | Collects trap notification info and send ARP to remote host.
SNMPGetNextIndex | To search for next index node in case of a Sequence variable.
Macros
Name | Description
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.
OID_MAX_LEN | Change this to match your OID string length.
SNMP_START_OF_VAR | This is macro SNMP_START_OF_VAR.
SNMP_END_OF_VAR | This is macro SNMP_END_OF_VAR.
SNMP_INDEX_INVALID | This is macro SNMP_INDEX_INVALID.
TRAP_TABLE_SIZE | Trap information. This table maintains list of intereseted receivers who should receive notifications when some interesting event occurs.
TRAP_COMMUNITY_MAX_LEN | This is macro TRAP_COMMUNITY_MAX_LEN.
NOTIFY_COMMUNITY_LEN | This is macro NOTIFY_COMMUNITY_LEN.
Module

SNMP

Structures
Name | Description
TRAP_INFO | This is type TRAP_INFO.
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.
SNMP_INDEX | This is type SNMP_INDEX.
Unions
Name | Description
SNMP_VAL | This is type SNMP_VAL.
Variables
Name | Description
gSendTrapFlag | global flag to send Trap
gSetTrapSendFlag | #if defined(SNMP_STACK_USE_V2_TRAP) || defined(SNMP_V1_V2_TRAP_WITH_SNMPV3) //if gSetTrapSendFlag == FALSE then the last varbind variable for //multiple varbind variable pdu structure or if there is only varbind variable send. // if gSetTrapSendFlag == TRUE, then v2 trap pdu is expecting more varbind variable. BYTE gSetTrapSendFlag = FALSE; #endif
gGenericTrapNotification | Global flag for Generic trap notification
gSpecificTrapNotification | Vendor specific trap code
gOIDCorrespondingSnmpMibID | Gloabal var to store SNMP ID of var for OID received in SNMP request.
Stack API > SNMP > Public Members


GENERIC_TRAP_NOTIFICATION_TYPE Enumeration

Contents | Index | Home
Previous | Up | Next
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.

Stack API > SNMP > Public Members > GENERIC_TRAP_NOTIFICATION_TYPE Enumeration


VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE Enumeration

Contents | Index | Home
Previous | Up | Next
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.

Stack API > SNMP > Public Members > VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE Enumeration


SNMP_ACTION Enumeration

Contents | Index | Home
Previous | Up | Next
SNMP_ACTION Enumeration
C
typedef enum {
  SNMP_GET = 0xa0,
  SNMP_GET_NEXT = 0xa1,
  SNMP_GET_RESPONSE = 0xa2,
  SNMP_SET = 0xa3,
  SNMP_TRAP = 0xa4,
  SNMP_V2C_GET_BULK = 0xa5,
  SNMP_V2_TRAP = 0xa7,
  SNMPV3_ENCRYPTION = 0x04,
  SNMP_ACTION_UNKNOWN = 0
} SNMP_ACTION;
Description

This is the list of SNMP action a remote NMS can perform. This inforamtion is passed to application via callback SNMPValidateCommunity(). Application should validate the action for given community string.

Members
Members | Description
SNMP_GET = 0xa0 | Snmp GET identifier
SNMP_GET_NEXT = 0xa1 | Snmp GET_NEXT identifier
SNMP_GET_RESPONSE = 0xa2 | Snmp GET_RESPONSE identifier
SNMP_SET = 0xa3 | Snmp SET identifier
SNMP_TRAP = 0xa4 | Snmp TRAP identifier
SNMP_V2C_GET_BULK = 0xa5 | Snmp GET_BULK identifier
SNMP_V2_TRAP = 0xa7 | Snmp v2 Trap Identifier
SNMP_ACTION_UNKNOWN = 0 | Snmp requested action unknown
Stack API > SNMP > Public Members > SNMP_ACTION Enumeration


COMMUNITY_TYPE Enumeration

Contents | Index | Home
Previous | Up | Next
COMMUNITY_TYPE Enumeration
C
typedef enum {
  READ_COMMUNITY = 1,
  WRITE_COMMUNITY = 2,
  INVALID_COMMUNITY = 3
} COMMUNITY_TYPE;
Description

This is type COMMUNITY_TYPE.

Members
Members | Description
READ_COMMUNITY = 1 | Read only community
WRITE_COMMUNITY = 2 | Read write community
INVALID_COMMUNITY = 3 | Community invalid
Stack API > SNMP > Public Members > COMMUNITY_TYPE Enumeration


SNMP_VAL Union

Contents | Index | Home
Previous | Up | Next
SNMP_VAL Union
C
typedef union {
  DWORD dword;
  WORD word;
  BYTE byte;
  BYTE v[sizeof(DWORD)];
} SNMP_VAL;
Description

This is type SNMP_VAL.

Members
Members | Description
DWORD dword; | double word value
WORD word; | word value
BYTE byte; | byte value
BYTE v[sizeof(DWORD)]; | byte array
Stack API > SNMP > Public Members > SNMP_VAL Union


TRAP_INFO Structure

Contents | Index | Home
Previous | Up | Next
TRAP_INFO Structure
C
typedef struct {
  BYTE Size;
  struct {
    BYTE communityLen;
    char community[TRAP_COMMUNITY_MAX_LEN];
    IP_ADDR IPAddress;
    struct {
      unsigned int bEnabled : 1;
    } Flags;
  } table[TRAP_TABLE_SIZE];
} TRAP_INFO;
Description

This is type TRAP_INFO.

Members
Members | Description
BYTE communityLen; | Community name length
char community[TRAP_COMMUNITY_MAX_LEN]; | Community name array
IP_ADDR IPAddress; | IP address to which trap to be sent
unsigned int bEnabled : 1; | Trap enabled flag
Stack API > SNMP > Public Members > TRAP_INFO Structure


gSendTrapFlag Variable

Contents | Index | Home
Previous | Up | Next
gSendTrapFlag Variable
C
BYTE gSendTrapFlag = FALSE;
Description

global flag to send Trap

Stack API > SNMP > Public Members > gSendTrapFlag Variable


gSetTrapSendFlag Variable

Contents | Index | Home
Previous | Up | Next
gSetTrapSendFlag Variable
C
BYTE gSetTrapSendFlag = FALSE;
Description

#if defined(SNMP_STACK_USE_V2_TRAP) || defined(SNMP_V1_V2_TRAP_WITH_SNMPV3) //if gSetTrapSendFlag == FALSE then the last varbind variable for //multiple varbind variable pdu structure or if there is only varbind variable send. // if gSetTrapSendFlag == TRUE, then v2 trap pdu is expecting more varbind variable. BYTE gSetTrapSendFlag = FALSE; #endif

Stack API > SNMP > Public Members > gSetTrapSendFlag Variable


gGenericTrapNotification Variable

Contents | Index | Home
Previous | Up | Next
gGenericTrapNotification Variable
C
BYTE gGenericTrapNotification = ENTERPRISE_SPECIFIC;
Description

Global flag for Generic trap notification

Stack API > SNMP > Public Members > gGenericTrapNotification Variable


gSpecificTrapNotification Variable

Contents | Index | Home
Previous | Up | Next
gSpecificTrapNotification Variable
C
BYTE gSpecificTrapNotification = VENDOR_TRAP_DEFAULT;
Description

Vendor specific trap code

Stack API > SNMP > Public Members > gSpecificTrapNotification Variable


gOIDCorrespondingSnmpMibID Variable

Contents | Index | Home
Previous | Up | Next
gOIDCorrespondingSnmpMibID Variable
C
BYTE gOIDCorrespondingSnmpMibID = MICROCHIP;
Description

Gloabal var to store SNMP ID of var for OID received in SNMP request.

Stack API > SNMP > Public Members > gOIDCorrespondingSnmpMibID Variable


SNMPSendTrap Function

Contents | Index | Home
Previous | Up | Next
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 SNMPIsNotifyReady() 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.

Stack API > SNMP > Public Members > SNMPSendTrap Function


SNMPValidateCommunity Function

Contents | Index | Home
Previous | Up | Next
SNMPValidateCommunity Function
C
BYTE SNMPValidateCommunity(
    BYTE* community
);
Description

This is function SNMPValidateCommunity.

Stack API > SNMP > Public Members > SNMPValidateCommunity Function


SNMPNotify Function

Contents | Index | Home
Previous | Up | Next
SNMPNotify Function
C
BOOL SNMPNotify(
    SNMP_ID var,
    SNMP_VAL val,
    SNMP_INDEX index
);
Description

This function creates SNMP trap PDU and sends it to previously specified remoteHost. snmpv1 trap pdu: | PDU-type | enterprise | agent-addr | generic-trap | specific-trap | | time-stamp | varbind-list |

The v1 enterprise is mapped directly to SNMPv2TrapOID.0

Preconditions

SNMPIsNotifyReady() 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 BYTE, WORD or DWORD 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 MPFS 2) Given var does not exist. 3) Previously given agentID does not exist
4) Data type of given var is unknown | only possible if MPFS itself was corrupted.
Remarks

This would fail if there were not UDP socket to open.

Stack API > SNMP > Public Members > SNMPNotify Function


SNMPSetVar Function

Contents | Index | Home
Previous | Up | Next
SNMPSetVar Function
C
BOOL SNMPSetVar(
    SNMP_ID var,
    SNMP_INDEX index,
    BYTE ref,
    SNMP_VAL val
);
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

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 BYTE, variable value is in val->byte If var data type is WORD, variable value is in val->word If var data type is DWORD, 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.

Stack API > SNMP > Public Members > SNMPSetVar Function


SNMPGetVar Function

Contents | Index | Home
Previous | Up | Next
SNMPGetVar Function
C
BOOL SNMPGetVar(
    SNMP_ID var,
    SNMP_INDEX index,
    BYTE* 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 BYTE, transfer data in val->byte If var data type is WORD, transfer data in val->word If var data type is DWORD, 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.

Stack API > SNMP > Public Members > SNMPGetVar Function


SNMPIsNotifyReady Function

Contents | Index | Home
Previous | Up | Next
SNMPIsNotifyReady Function
C
BOOL SNMPIsNotifyReady(
    IP_ADDR* remoteHost
);
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

SNMPNotifyPrepare() 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 SNMPNotify may be called.
FALSE | If remoteHost IP address is not resolved.
Remarks

This would fail if there were not UDP socket to open.

Stack API > SNMP > Public Members > SNMPIsNotifyReady Function


SNMPNotifyPrepare Function

Contents | Index | Home
Previous | Up | Next
SNMPNotifyPrepare Function
C
void SNMPNotifyPrepare(
    IP_ADDR* remoteHost,
    char* community,
    BYTE communityLen,
    SNMP_ID agentIDVar,
    BYTE notificationCode,
    DWORD 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

SNMPInit() 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.

Stack API > SNMP > Public Members > SNMPNotifyPrepare Function


SNMPGetNextIndex Function

Contents | Index | Home
Previous | Up | Next
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.
FALSE | Otherwise.
Remarks

Only sequence index needs to be handled in this function.

Stack API > SNMP > Public Members > SNMPGetNextIndex Function


SNMP_ID Type

Contents | Index | Home
Previous | Up | Next
SNMP_ID Type
C
typedef int 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.

Stack API > SNMP > Public Members > SNMP_ID Type


SNMP_INDEX Type

Contents | Index | Home
Previous | Up | Next
SNMP_INDEX Type
C
typedef BYTE SNMP_INDEX;
Description

This is type SNMP_INDEX.

Stack API > SNMP > Public Members > SNMP_INDEX Type


SNMP_COMMUNITY_MAX_LEN Macro

Contents | Index | Home
Previous | Up | Next
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.

Stack API > SNMP > Public Members > SNMP_COMMUNITY_MAX_LEN Macro


OID_MAX_LEN Macro

Contents | Index | Home
Previous | Up | Next
OID_MAX_LEN Macro
C
#define OID_MAX_LEN (18)
Description

Change this to match your OID string length.

Stack API > SNMP > Public Members > OID_MAX_LEN Macro


SNMP_START_OF_VAR Macro

Contents | Index | Home
Previous | Up | Next
SNMP_START_OF_VAR Macro
C
#define SNMP_START_OF_VAR (0)
Description

This is macro SNMP_START_OF_VAR.

Stack API > SNMP > Public Members > SNMP_START_OF_VAR Macro


SNMP_END_OF_VAR Macro

Contents | Index | Home
Previous | Up | Next
SNMP_END_OF_VAR Macro
C
#define SNMP_END_OF_VAR (0xff)
Description

This is macro SNMP_END_OF_VAR.

Stack API > SNMP > Public Members > SNMP_END_OF_VAR Macro


SNMP_INDEX_INVALID Macro

Contents | Index | Home
Previous | Up | Next
SNMP_INDEX_INVALID Macro
C
#define SNMP_INDEX_INVALID (0xff)
Description

This is macro SNMP_INDEX_INVALID.

Stack API > SNMP > Public Members > SNMP_INDEX_INVALID Macro


TRAP_TABLE_SIZE Macro

Contents | Index | Home
Previous | Up | Next
TRAP_TABLE_SIZE Macro
C
#define TRAP_TABLE_SIZE (2)
Description

Trap information. This table maintains list of intereseted receivers who should receive notifications when some interesting event occurs.

Stack API > SNMP > Public Members > TRAP_TABLE_SIZE Macro


TRAP_COMMUNITY_MAX_LEN Macro

Contents | Index | Home
Previous | Up | Next
TRAP_COMMUNITY_MAX_LEN Macro
C
#define TRAP_COMMUNITY_MAX_LEN (8)
Description

This is macro TRAP_COMMUNITY_MAX_LEN.

Stack API > SNMP > Public Members > TRAP_COMMUNITY_MAX_LEN Macro


NOTIFY_COMMUNITY_LEN Macro

Contents | Index | Home
Previous | Up | Next
NOTIFY_COMMUNITY_LEN Macro
C
#define NOTIFY_COMMUNITY_LEN (SNMP_COMMUNITY_MAX_LEN)
Description

This is macro NOTIFY_COMMUNITY_LEN.

Stack API > SNMP > Public Members > NOTIFY_COMMUNITY_LEN Macro


SNMP Internal Members

Contents | Index | Home
Previous | Up | Next
SNMP Internal Members

The following functions and variables are designated as internal to the SNMP module.

Enumerations
Name | Description
DATA_TYPE |
SNMP_ERR_STATUS |
Functions
Name | Description
_SNMPDuplexInit |
_SNMPGet | This is function _SNMPGet.
_SNMPPut |
FindOIDsInRequest | This is function FindOIDsInRequest.
GetDataTypeInfo | This is function GetDataTypeInfo.
IsASNNull | static BYTE IsValidStructure(WORD* dataLen);
SetErrorStatus | This is function SetErrorStatus.
IsValidLength | This is function IsValidLength.
GetDataTypeInfo | This is function GetDataTypeInfo.
GetNextLeaf | This is function GetNextLeaf.
GetOIDStringByAddr | This is function GetOIDStringByAddr.
GetOIDStringByID | This function is used only when TRAP is enabled.
IsValidCommunity | This is function IsValidCommunity.
IsValidInt | This is function IsValidInt.
IsValidLength | This is function IsValidLength.
IsValidOID |
IsValidPDU | static BOOL IsValidInt(DWORD* val);
IsValidStructure | This is function IsValidStructure.
OIDLookup |
ProcessGetSetHeader | Validates the received udp packet Get/Set request header.
ProcessHeader | Validates the received udp packet Snmp header.
ProcessSetVar | This is function ProcessSetVar.
ProcessVariables | This routine processes the snmp request and parallely creates the response pdu.
ReadMIBRecord | This is function ReadMIBRecord.
SNMPCheckIfPvtMibObjRequested |
Macros
Name | Description
_SNMPGetTxOffset | This is macro _SNMPGetTxOffset.
_SNMPSetTxOffset |
AGENT_NOTIFY_PORT | This is macro AGENT_NOTIFY_PORT.
ASN_INT | This is macro ASN_INT.
ASN_NULL | This is macro ASN_NULL.
ASN_OID | This is macro ASN_OID.
DATA_TYPE_TABLE_SIZE |
GET_BULK_REQUEST | This is macro GET_BULK_REQUEST.
GET_NEXT_REQUEST | This is macro GET_NEXT_REQUEST.
GET_REQUEST |
GET_RESPONSE | This is macro GET_RESPONSE.
IS_AGENT_PDU | This is macro IS_AGENT_PDU.
IS_ASN_INT | This is macro IS_ASN_INT.
IS_ASN_NULL | This is macro IS_ASN_NULL.
IS_GET_NEXT_REQUEST | This is macro IS_GET_NEXT_REQUEST.
IS_GET_REQUEST | This is macro IS_GET_REQUEST.
IS_GET_RESPONSE | This is macro IS_GET_RESPONSE.
IS_OCTET_STRING | This is macro IS_OCTET_STRING.
IS_OID | This is macro IS_OID.
IS_SET_REQUEST | This is macro IS_SET_REQUEST.
IS_STRUCTURE |
IS_TRAP | This is macro IS_TRAP.
OCTET_STRING | This is macro OCTET_STRING.
SET_REQUEST | This is macro SET_REQUEST.
SNMP_AGENT_PORT |
SNMP_BIB_FILE_NAME | This is the file that contains SNMP bib file. File name must contain all upper case letter and must match with what was included in MPFS2 image.
SNMP_COUNTER32 | This is macro SNMP_COUNTER32.
SNMP_GAUGE32 | This is macro SNMP_GAUGE32.
SNMP_IP_ADDR | This is macro SNMP_IP_ADDR.
SNMP_NMS_PORT | This is macro SNMP_NMS_PORT.
SNMP_NSAP_ADDR | This is macro SNMP_NSAP_ADDR.
SNMP_OPAQUE | This is macro SNMP_OPAQUE.
SNMP_TIME_TICKS | This is macro SNMP_TIME_TICKS.
SNMP_V1 |
SNMP_V2C | This is macro SNMP_V2C.
STRUCTURE |
TRAP | This is macro TRAP.
Module

SNMP

Structures
Name | Description
DATA_TYPE_INFO |
OID_INFO |
PDU_INFO |
reqVarErrStatus |
SNMP_NOTIFY_INFO |
Unions
Name | Description
INDEX_INFO |
MIB_INFO |
SNMP_STATUS |
Variables
Name | Description
appendZeroToOID | global flag to modify OID by appending zero
dataTypeTable | ASN format datatype for snmp v1 and v2c
hMPFS | MPFS file handler
SNMPAgentSocket | Snmp udp socket
SNMPNotifyInfo | notify info for trap
snmpReqVarErrStatus | vars from req list processing err status
SNMPRxOffset | Snmp udp buffer rx offset
SNMPStatus | MIB file access status
SNMPTxOffset | Snmp udp buffer tx offset
trapInfo | Initialize trap table with no entries.
Stack API > SNMP > Internal Members


_SNMPDuplexInit Function

Contents | Index | Home
Previous | Up | Next
_SNMPDuplexInit Function
C
void _SNMPDuplexInit(
    UDP_SOCKET socket
);
Stack API > SNMP > Internal Members > _SNMPDuplexInit Function


_SNMPGet Function

Contents | Index | Home
Previous | Up | Next
_SNMPGet Function
C
BYTE _SNMPGet();
Description

This is function _SNMPGet.

Stack API > SNMP > Internal Members > _SNMPGet Function


_SNMPGetTxOffset Macro

Contents | Index | Home
Previous | Up | Next
_SNMPGetTxOffset Macro
C
#define _SNMPGetTxOffset SNMPTxOffset
Description

This is macro _SNMPGetTxOffset.

Stack API > SNMP > Internal Members > _SNMPGetTxOffset Macro


_SNMPPut Function

Contents | Index | Home
Previous | Up | Next
_SNMPPut Function
C
void _SNMPPut(
    BYTE v
);
Stack API > SNMP > Internal Members > _SNMPPut Function


_SNMPSetTxOffset Macro

Contents | Index | Home
Previous | Up | Next
_SNMPSetTxOffset Macro
C
#define _SNMPSetTxOffset(o) (SNMPTxOffset = o)
Stack API > SNMP > Internal Members > _SNMPSetTxOffset Macro


AGENT_NOTIFY_PORT Macro

Contents | Index | Home
Previous | Up | Next
AGENT_NOTIFY_PORT Macro
C
#define AGENT_NOTIFY_PORT (0xfffe)
Description

This is macro AGENT_NOTIFY_PORT.

Stack API > SNMP > Internal Members > AGENT_NOTIFY_PORT Macro


appendZeroToOID Variable

Contents | Index | Home
Previous | Up | Next
appendZeroToOID Variable
C
BYTE appendZeroToOID;
Description

global flag to modify OID by appending zero

Stack API > SNMP > Internal Members > appendZeroToOID Variable


ASN_INT Macro

Contents | Index | Home
Previous | Up | Next
ASN_INT Macro
C
#define ASN_INT (0x02u)
Description

This is macro ASN_INT.

Stack API > SNMP > Internal Members > ASN_INT Macro


ASN_NULL Macro

Contents | Index | Home
Previous | Up | Next
ASN_NULL Macro
C
#define ASN_NULL (0x05u)
Description

This is macro ASN_NULL.

Stack API > SNMP > Internal Members > ASN_NULL Macro


ASN_OID Macro

Contents | Index | Home
Previous | Up | Next
ASN_OID Macro
C
#define ASN_OID (0x06u)
Description

This is macro ASN_OID.

Stack API > SNMP > Internal Members > ASN_OID Macro


DATA_TYPE Enumeration

Contents | Index | Home
Previous | Up | Next
DATA_TYPE Enumeration
C
typedef enum {
  INT8_VAL = 0x00,
  INT16_VAL = 0x01,
  INT32_VAL = 0x02,
  BYTE_ARRAY = 0x03,
  ASCII_STRING = 0x04,
  IP_ADDRESS = 0x05,
  COUNTER32 = 0x06,
  TIME_TICKS_VAL = 0x07,
  GAUGE32 = 0x08,
  OID_VAL = 0x09,
  DATA_TYPE_UNKNOWN
} DATA_TYPE;
Members
Members | Description
INT8_VAL = 0x00 | 8 bit integer value
INT16_VAL = 0x01 | 16 bit integer value
INT32_VAL = 0x02 | 32 bit integer value
BYTE_ARRAY = 0x03 | Aray of bytes
ASCII_STRING = 0x04 | Ascii string type
IP_ADDRESS = 0x05 | IP address variable
COUNTER32 = 0x06 | 32 bit counter variable
TIME_TICKS_VAL = 0x07 | Timer vakue counter variable
GAUGE32 = 0x08 | 32 bit guage variable
OID_VAL = 0x09 | Object id value var
DATA_TYPE_UNKNOWN | Unknown data type
Stack API > SNMP > Internal Members > DATA_TYPE Enumeration


DATA_TYPE_INFO Structure

Contents | Index | Home
Previous | Up | Next
DATA_TYPE_INFO Structure
C
typedef struct {
  BYTE asnType;
  BYTE asnLen;
} DATA_TYPE_INFO;
Members
Members | Description
BYTE asnType; | ASN data type
BYTE asnLen; | ASN data length
Stack API > SNMP > Internal Members > DATA_TYPE_INFO Structure


DATA_TYPE_TABLE_SIZE Macro

Contents | Index | Home
Previous | Up | Next
DATA_TYPE_TABLE_SIZE Macro
C
#define DATA_TYPE_TABLE_SIZE (sizeof(dataTypeTable)/sizeof(dataTypeTable[0]))
Stack API > SNMP > Internal Members > DATA_TYPE_TABLE_SIZE Macro


dataTypeTable Variable

Contents | Index | Home
Previous | Up | Next
dataTypeTable Variable
C
ROM DATA_TYPE_INFO dataTypeTable[] = { { ASN_INT, 1 }, { ASN_INT, 2 }, { ASN_INT, 4 }, { OCTET_STRING, 0xff }, { OCTET_STRING, 0xff }, { SNMP_IP_ADDR, 4 }, { SNMP_COUNTER32, 4 }, { SNMP_TIME_TICKS, 4 }, { SNMP_GAUGE32, 4 }, { ASN_OID, 0xff } };
Description

ASN format datatype for snmp v1 and v2c

Stack API > SNMP > Internal Members > dataTypeTable Variable


FindOIDsInRequest Function

Contents | Index | Home
Previous | Up | Next
FindOIDsInRequest Function
C
static BYTE FindOIDsInRequest(
    WORD pdulen
);
Description

This is function FindOIDsInRequest.

Stack API > SNMP > Internal Members > FindOIDsInRequest Function


GET_BULK_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
GET_BULK_REQUEST Macro
C
#define GET_BULK_REQUEST (0xa5)
Description

This is macro GET_BULK_REQUEST.

Stack API > SNMP > Internal Members > GET_BULK_REQUEST Macro


GET_NEXT_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
GET_NEXT_REQUEST Macro
C
#define GET_NEXT_REQUEST (0xa1)
Description

This is macro GET_NEXT_REQUEST.

Stack API > SNMP > Internal Members > GET_NEXT_REQUEST Macro


GET_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
GET_REQUEST Macro
C
#define GET_REQUEST (0xa0)
Stack API > SNMP > Internal Members > GET_REQUEST Macro


GET_RESPONSE Macro

Contents | Index | Home
Previous | Up | Next
GET_RESPONSE Macro
C
#define GET_RESPONSE (0xa2)
Description

This is macro GET_RESPONSE.

Stack API > SNMP > Internal Members > GET_RESPONSE Macro


hMPFS Variable

Contents | Index | Home
Previous | Up | Next
hMPFS Variable
C
MPFS_HANDLE hMPFS;
Description

MPFS file handler

Stack API > SNMP > Internal Members > hMPFS Variable


INDEX_INFO Union

Contents | Index | Home
Previous | Up | Next
INDEX_INFO Union
C
typedef union {
  struct {
    unsigned int bIsOID : 1;
  } Flags;
  BYTE Val;
} INDEX_INFO;
Members
Members | Description
unsigned int bIsOID : 1; | value is OID/index int flag
BYTE Val; | value is OID/index byte flag
Stack API > SNMP > Internal Members > INDEX_INFO Union


IS_AGENT_PDU Macro

Contents | Index | Home
Previous | Up | Next
IS_AGENT_PDU Macro
C
#define IS_AGENT_PDU(a) (a==GET_REQUEST || \
                                 a==GET_NEXT_REQUEST || \
                                 a==SET_REQUEST || \
                                 a==SNMP_V2C_GET_BULK)
Description

This is macro IS_AGENT_PDU.

Stack API > SNMP > Internal Members > IS_AGENT_PDU Macro


IS_ASN_INT Macro

Contents | Index | Home
Previous | Up | Next
IS_ASN_INT Macro
C
#define IS_ASN_INT(a) (a==ASN_INT)
Description

This is macro IS_ASN_INT.

Stack API > SNMP > Internal Members > IS_ASN_INT Macro


IS_ASN_NULL Macro

Contents | Index | Home
Previous | Up | Next
IS_ASN_NULL Macro
C
#define IS_ASN_NULL(a) (a==ASN_NULL)
Description

This is macro IS_ASN_NULL.

Stack API > SNMP > Internal Members > IS_ASN_NULL Macro


IS_GET_NEXT_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
IS_GET_NEXT_REQUEST Macro
C
#define IS_GET_NEXT_REQUEST(a) (a==GET_NEXT_REQUEST)
Description

This is macro IS_GET_NEXT_REQUEST.

Stack API > SNMP > Internal Members > IS_GET_NEXT_REQUEST Macro


IS_GET_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
IS_GET_REQUEST Macro
C
#define IS_GET_REQUEST(a) (a==GET_REQUEST)
Description

This is macro IS_GET_REQUEST.

Stack API > SNMP > Internal Members > IS_GET_REQUEST Macro


IS_GET_RESPONSE Macro

Contents | Index | Home
Previous | Up | Next
IS_GET_RESPONSE Macro
C
#define IS_GET_RESPONSE(a) (a==GET_RESPONSE)
Description

This is macro IS_GET_RESPONSE.

Stack API > SNMP > Internal Members > IS_GET_RESPONSE Macro


IS_OCTET_STRING Macro

Contents | Index | Home
Previous | Up | Next
IS_OCTET_STRING Macro
C
#define IS_OCTET_STRING(a) (a==OCTET_STRING)
Description

This is macro IS_OCTET_STRING.

Stack API > SNMP > Internal Members > IS_OCTET_STRING Macro


IS_OID Macro

Contents | Index | Home
Previous | Up | Next
IS_OID Macro
C
#define IS_OID(a) (a==ASN_OID)
Description

This is macro IS_OID.

Stack API > SNMP > Internal Members > IS_OID Macro


GetDataTypeInfo Function

Contents | Index | Home
Previous | Up | Next
GetDataTypeInfo Function
C
BOOL GetDataTypeInfo(
    DATA_TYPE dataType,
    DATA_TYPE_INFO * info
);
Description

This is function GetDataTypeInfo.

Stack API > SNMP > Internal Members > GetDataTypeInfo Function


IS_SET_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
IS_SET_REQUEST Macro
C
#define IS_SET_REQUEST(a) (a==SET_REQUEST)
Description

This is macro IS_SET_REQUEST.

Stack API > SNMP > Internal Members > IS_SET_REQUEST Macro


IS_STRUCTURE Macro

Contents | Index | Home
Previous | Up | Next
IS_STRUCTURE Macro
C
#define IS_STRUCTURE(a) (a==STRUCTURE)
Stack API > SNMP > Internal Members > IS_STRUCTURE Macro


IS_TRAP Macro

Contents | Index | Home
Previous | Up | Next
IS_TRAP Macro
C
#define IS_TRAP(a) (a==TRAP)
Description

This is macro IS_TRAP.

Stack API > SNMP > Internal Members > IS_TRAP Macro


IsASNNull Function

Contents | Index | Home
Previous | Up | Next
IsASNNull Function
C
static BOOL IsASNNull();
Description

static BYTE IsValidStructure(WORD* dataLen);

Stack API > SNMP > Internal Members > IsASNNull Function


MIB_INFO Union

Contents | Index | Home
Previous | Up | Next
MIB_INFO Union
C
typedef union {
  struct {
    unsigned int bIsDistantSibling : 1;
    unsigned int bIsConstant : 1;
    unsigned int bIsSequence : 1;
    unsigned int bIsSibling : 1;
    unsigned int bIsParent : 1;
    unsigned int bIsEditable : 1;
    unsigned int bIsAgentID : 1;
    unsigned int bIsIDPresent : 1;
  } Flags;
  BYTE Val;
} MIB_INFO;
Members
Members | Description
unsigned int bIsDistantSibling : 1; | Object have distant sibling node
unsigned int bIsConstant : 1; | Object is constant
unsigned int bIsSequence : 1; | Object is sequence
unsigned int bIsSibling : 1; | Sibling node flag
unsigned int bIsParent : 1; | Node is parent flag
unsigned int bIsEditable : 1; | Node is editable flag
unsigned int bIsAgentID : 1; | Node have agent id flag
unsigned int bIsIDPresent : 1; | Id present flag
BYTE Val; | MIB Obj info as byte value
Stack API > SNMP > Internal Members > MIB_INFO Union


OCTET_STRING Macro

Contents | Index | Home
Previous | Up | Next
OCTET_STRING Macro
C
#define OCTET_STRING (0x04u)
Description

This is macro OCTET_STRING.

Stack API > SNMP > Internal Members > OCTET_STRING Macro


OID_INFO Structure

Contents | Index | Home
Previous | Up | Next
OID_INFO Structure
C
typedef struct {
  DWORD hNode;
  BYTE oid;
  MIB_INFO nodeInfo;
  DATA_TYPE dataType;
  SNMP_ID id;
  WORD_VAL dataLen;
  DWORD hData;
  DWORD hSibling;
  DWORD hChild;
  BYTE index;
  BYTE indexLen;
} OID_INFO;
Members
Members | Description
DWORD hNode; | Node location in the mib
BYTE oid; | Object Id
MIB_INFO nodeInfo; | Node info
DATA_TYPE dataType; | Data type
SNMP_ID id; | Snmp Id
WORD_VAL dataLen; | Data length
DWORD hData; | Data
DWORD hSibling; | Sibling info
DWORD hChild; | Child info
BYTE index; | Index of object
BYTE indexLen; | Index length
Stack API > SNMP > Internal Members > OID_INFO Structure


PDU_INFO Structure

Contents | Index | Home
Previous | Up | Next
PDU_INFO Structure
C
typedef struct {
  DWORD_VAL requestID;
  BYTE nonRepeators;
  BYTE maxRepetitions;
  BYTE pduType;
  BYTE errorStatus;
  BYTE erroIndex;
  BYTE snmpVersion;
  WORD pduLength;
} PDU_INFO;
Members
Members | Description
DWORD_VAL requestID; | Snmp request id
BYTE nonRepeators; | non repeaters in the request
BYTE maxRepetitions; | max repeaters in the request
BYTE pduType; | Snmp pdu type
BYTE errorStatus; | Pdu error status
BYTE erroIndex; | Pdu error Index
BYTE snmpVersion; | Snmp version
WORD pduLength; | Pdu length
Stack API > SNMP > Internal Members > PDU_INFO Structure


reqVarErrStatus Structure

Contents | Index | Home
Previous | Up | Next
reqVarErrStatus Structure
C
typedef struct {
  WORD noSuchObjectErr;
  WORD noSuchNameErr;
  WORD noSuchInstanceErr;
  WORD endOfMibViewErr;
} reqVarErrStatus;
Members
Members | Description
WORD noSuchObjectErr; | Var list no such obj errors flags
WORD noSuchNameErr; | Var list no such name error
WORD noSuchInstanceErr; | Var list no such instance error
WORD endOfMibViewErr; | Var list end of mib view error
Stack API > SNMP > Internal Members > reqVarErrStatus Structure


SET_REQUEST Macro

Contents | Index | Home
Previous | Up | Next
SET_REQUEST Macro
C
#define SET_REQUEST (0xa3)
Description

This is macro SET_REQUEST.

Stack API > SNMP > Internal Members > SET_REQUEST Macro


SetErrorStatus Function

Contents | Index | Home
Previous | Up | Next
SetErrorStatus Function
C
void SetErrorStatus(
    WORD errorStatusOffset,
    WORD errorIndexOffset,
    SNMP_ERR_STATUS errorStatus,
    BYTE errorIndex
);
Description

This is function SetErrorStatus.

Stack API > SNMP > Internal Members > SetErrorStatus Function


SNMP_AGENT_PORT Macro

Contents | Index | Home
Previous | Up | Next
SNMP_AGENT_PORT Macro
C
#define SNMP_AGENT_PORT (161)
Stack API > SNMP > Internal Members > SNMP_AGENT_PORT Macro


SNMP_BIB_FILE_NAME Macro

Contents | Index | Home
Previous | Up | Next
SNMP_BIB_FILE_NAME Macro
C
#define SNMP_BIB_FILE_NAME "snmp.bib"
Description

This is the file that contains SNMP bib file. File name must contain all upper case letter and must match with what was included in MPFS2 image.

Stack API > SNMP > Internal Members > SNMP_BIB_FILE_NAME Macro


SNMP_COUNTER32 Macro

Contents | Index | Home
Previous | Up | Next
SNMP_COUNTER32 Macro
C
#define SNMP_COUNTER32 (0x41)
Description

This is macro SNMP_COUNTER32.

Stack API > SNMP > Internal Members > SNMP_COUNTER32 Macro


SNMP_ERR_STATUS Enumeration

Contents | Index | Home
Previous | Up | Next
SNMP_ERR_STATUS Enumeration
C
typedef enum {
  SNMP_NO_ERR = 0,
  SNMP_TOO_BIG,
  SNMP_NO_SUCH_NAME,
  SNMP_BAD_VALUE,
  SNMP_READ_ONLY,
  SNMP_GEN_ERR,
  SNMP_NO_ACCESS,
  SNMP_WRONG_TYPE,
  SNMP_WRONG_LENGTH,
  SNMP_WRONG_ENCODING,
  SNMP_WRONG_VALUE,
  SNMP_NO_CREATION,
  SNMP_INCONSISTENT_VAL,
  SNMP_RESOURCE_UNAVAILABE,
  SNMP_COMMIT_FAILED,
  SNMP_UNDO_FAILED,
  SNMP_AUTH_ERROR,
  SNMP_NOT_WRITABLE,
  SNMP_INCONSISTENT_NAME,
  SNMP_NO_SUCH_OBJ = 128,
  SNMP_NO_SUCH_INSTANCE = 129,
  SNMP_END_OF_MIB_VIEW = 130
} SNMP_ERR_STATUS;
Members
Members | Description
SNMP_NO_ERR = 0 | Snmp no error
SNMP_TOO_BIG | Value too big error
SNMP_NO_SUCH_NAME | No such name in MIB error
SNMP_BAD_VALUE | Not assignable value for the var error
SNMP_READ_ONLY | Read only variable, write not allowed err
SNMP_GEN_ERR | Snmp gen error
SNMP_NO_ACCESS | Access to modify or read not granted err
SNMP_WRONG_TYPE | Variable data type wrong error
SNMP_WRONG_LENGTH | Wrong data length error
SNMP_WRONG_ENCODING | Wrong encoding error
SNMP_WRONG_VALUE | Wrong value for the var type
SNMP_NO_CREATION | No creationg error
SNMP_INCONSISTENT_VAL | Inconsistent value error
SNMP_RESOURCE_UNAVAILABE | Resource unavailbe error
SNMP_COMMIT_FAILED | Modification update failed error
SNMP_UNDO_FAILED | Modification undo failed
SNMP_AUTH_ERROR | Authorization failed error
SNMP_NOT_WRITABLE | Variable read only
SNMP_INCONSISTENT_NAME | Inconsistent name
SNMP_NO_SUCH_OBJ = 128 | No such object error
SNMP_NO_SUCH_INSTANCE = 129 | No such instance error
SNMP_END_OF_MIB_VIEW = 130 | Reached to end of mib error
Stack API > SNMP > Internal Members > SNMP_ERR_STATUS Enumeration


SNMP_GAUGE32 Macro

Contents | Index | Home
Previous | Up | Next
SNMP_GAUGE32 Macro
C
#define SNMP_GAUGE32 (0x42)
Description

This is macro SNMP_GAUGE32.

Stack API > SNMP > Internal Members > SNMP_GAUGE32 Macro


SNMP_IP_ADDR Macro

Contents | Index | Home
Previous | Up | Next
SNMP_IP_ADDR Macro
C
#define SNMP_IP_ADDR (0x40)
Description

This is macro SNMP_IP_ADDR.

Stack API > SNMP > Internal Members > SNMP_IP_ADDR Macro


SNMP_NMS_PORT Macro

Contents | Index | Home
Previous | Up | Next
SNMP_NMS_PORT Macro
C
#define SNMP_NMS_PORT (162)
Description

This is macro SNMP_NMS_PORT.

Stack API > SNMP > Internal Members > SNMP_NMS_PORT Macro


SNMP_NOTIFY_INFO Structure

Contents | Index | Home
Previous | Up | Next
SNMP_NOTIFY_INFO Structure
C
typedef struct {
  char community[NOTIFY_COMMUNITY_LEN];
  BYTE communityLen;
  SNMP_ID agentIDVar;
  BYTE notificationCode;
  UDP_SOCKET socket;
  DWORD_VAL timestamp;
  SNMP_ID trapIDVar;
} SNMP_NOTIFY_INFO;
Members
Members | Description
char community[NOTIFY_COMMUNITY_LEN]; | Community name array
BYTE communityLen; | Community name length
SNMP_ID agentIDVar; | Agent id for trap identification
BYTE notificationCode; | Trap notification code
UDP_SOCKET socket; | Udp socket number
DWORD_VAL timestamp; | Time stamp for trap
SNMP_ID trapIDVar; | SNMPV2 specific trap
Stack API > SNMP > Internal Members > SNMP_NOTIFY_INFO Structure


SNMP_NSAP_ADDR Macro

Contents | Index | Home
Previous | Up | Next
SNMP_NSAP_ADDR Macro
C
#define SNMP_NSAP_ADDR (0x45)
Description

This is macro SNMP_NSAP_ADDR.

Stack API > SNMP > Internal Members > SNMP_NSAP_ADDR Macro


IsValidLength Function

Contents | Index | Home
Previous | Up | Next
IsValidLength Function
C
BYTE IsValidLength(
    WORD * len
);
Description

This is function IsValidLength.

Stack API > SNMP > Internal Members > IsValidLength Function


SNMP_OPAQUE Macro

Contents | Index | Home
Previous | Up | Next
SNMP_OPAQUE Macro
C
#define SNMP_OPAQUE (0x44)
Description

This is macro SNMP_OPAQUE.

Stack API > SNMP > Internal Members > SNMP_OPAQUE Macro


SNMP_STATUS Union

Contents | Index | Home
Previous | Up | Next
SNMP_STATUS Union
C
typedef union {
  struct {
    unsigned int bIsFileOpen : 1;
  } Flags;
  BYTE Val;
} SNMP_STATUS;
Members
Members | Description
unsigned int bIsFileOpen : 1; | MIB file access int flag
BYTE Val; | MIB file access byte flag
Stack API > SNMP > Internal Members > SNMP_STATUS Union


SNMP_TIME_TICKS Macro

Contents | Index | Home
Previous | Up | Next
SNMP_TIME_TICKS Macro
C
#define SNMP_TIME_TICKS (0x43)
Description

This is macro SNMP_TIME_TICKS.

Stack API > SNMP > Internal Members > SNMP_TIME_TICKS Macro


SNMP_V1 Macro

Contents | Index | Home
Previous | Up | Next
SNMP_V1 Macro
C
#define SNMP_V1 (0)
Stack API > SNMP > Internal Members > SNMP_V1 Macro


SNMP_V2C Macro

Contents | Index | Home
Previous | Up | Next
SNMP_V2C Macro
C
#define SNMP_V2C (1)
Description

This is macro SNMP_V2C.

Stack API > SNMP > Internal Members > SNMP_V2C Macro


SNMPAgentSocket Variable

Contents | Index | Home
Previous | Up | Next
SNMPAgentSocket Variable
C
UDP_SOCKET SNMPAgentSocket = INVALID_UDP_SOCKET;
Description

Snmp udp socket

Stack API > SNMP > Internal Members > SNMPAgentSocket Variable


SNMPNotifyInfo Variable

Contents | Index | Home
Previous | Up | Next
SNMPNotifyInfo Variable
C
SNMP_NOTIFY_INFO SNMPNotifyInfo;
Description

notify info for trap

Stack API > SNMP > Internal Members > SNMPNotifyInfo Variable


snmpReqVarErrStatus Variable

Contents | Index | Home
Previous | Up | Next
snmpReqVarErrStatus Variable
C
reqVarErrStatus snmpReqVarErrStatus;
Description

vars from req list processing err status

Stack API > SNMP > Internal Members > snmpReqVarErrStatus Variable


SNMPRxOffset Variable

Contents | Index | Home
Previous | Up | Next
SNMPRxOffset Variable
C
WORD SNMPRxOffset;
Description

Snmp udp buffer rx offset

Stack API > SNMP > Internal Members > SNMPRxOffset Variable


SNMPStatus Variable

Contents | Index | Home
Previous | Up | Next
SNMPStatus Variable
C
SNMP_STATUS SNMPStatus;
Description

MIB file access status

Stack API > SNMP > Internal Members > SNMPStatus Variable


SNMPTxOffset Variable

Contents | Index | Home
Previous | Up | Next
SNMPTxOffset Variable
C
WORD SNMPTxOffset;
Description

Snmp udp buffer tx offset

Stack API > SNMP > Internal Members > SNMPTxOffset Variable


STRUCTURE Macro

Contents | Index | Home
Previous | Up | Next
STRUCTURE Macro
C
#define STRUCTURE (0x30u)
Stack API > SNMP > Internal Members > STRUCTURE Macro


TRAP Macro

Contents | Index | Home
Previous | Up | Next
TRAP Macro
C
#define TRAP (0xa4)
Description

This is macro TRAP.

Stack API > SNMP > Internal Members > TRAP Macro


trapInfo Variable

Contents | Index | Home
Previous | Up | Next
trapInfo Variable
C
TRAP_INFO trapInfo = { TRAP_TABLE_SIZE };
Description

Initialize trap table with no entries.

Stack API > SNMP > Internal Members > trapInfo Variable


GetDataTypeInfo Function

Contents | Index | Home
Previous | Up | Next
GetDataTypeInfo Function
C
BOOL GetDataTypeInfo(
    DATA_TYPE dataType,
    DATA_TYPE_INFO* info
);
Description

This is function GetDataTypeInfo.

Stack API > SNMP > Internal Members > GetDataTypeInfo Function


GetNextLeaf Function

Contents | Index | Home
Previous | Up | Next
GetNextLeaf Function
C
BOOL GetNextLeaf(
    OID_INFO* rec
);
Description

This is function GetNextLeaf.

Stack API > SNMP > Internal Members > GetNextLeaf Function


GetOIDStringByAddr Function

Contents | Index | Home
Previous | Up | Next
GetOIDStringByAddr Function
C
BOOL GetOIDStringByAddr(
    OID_INFO* rec,
    BYTE* oidString,
    BYTE* len
);
Description

This is function GetOIDStringByAddr.

Stack API > SNMP > Internal Members > GetOIDStringByAddr Function


GetOIDStringByID Function

Contents | Index | Home
Previous | Up | Next
GetOIDStringByID Function
C
BOOL GetOIDStringByID(
    SNMP_ID id,
    OID_INFO* info,
    BYTE* oidString,
    BYTE* len
);
Description

This function is used only when TRAP is enabled.

Stack API > SNMP > Internal Members > GetOIDStringByID Function


IsValidCommunity Function

Contents | Index | Home
Previous | Up | Next
IsValidCommunity Function
C
static BOOL IsValidCommunity(
    char* community,
    BYTE* len
);
Description

This is function IsValidCommunity.

Stack API > SNMP > Internal Members > IsValidCommunity Function


IsValidInt Function

Contents | Index | Home
Previous | Up | Next
IsValidInt Function
C
BOOL IsValidInt(
    DWORD* val
);
Description

This is function IsValidInt.

Stack API > SNMP > Internal Members > IsValidInt Function


IsValidLength Function

Contents | Index | Home
Previous | Up | Next
IsValidLength Function
C
BYTE IsValidLength(
    WORD* len
);
Description

This is function IsValidLength.

Stack API > SNMP > Internal Members > IsValidLength Function


IsValidOID Function

Contents | Index | Home
Previous | Up | Next
IsValidOID Function
C
static BOOL IsValidOID(
    BYTE* oid,
    BYTE* len
);
Stack API > SNMP > Internal Members > IsValidOID Function


IsValidPDU Function

Contents | Index | Home
Previous | Up | Next
IsValidPDU Function
C
static BOOL IsValidPDU(
    SNMP_ACTION* pdu
);
Description

static BOOL IsValidInt(DWORD* val);

Stack API > SNMP > Internal Members > IsValidPDU Function


IsValidStructure Function

Contents | Index | Home
Previous | Up | Next
IsValidStructure Function
C
BYTE IsValidStructure(
    WORD* dataLen
);
Description

This is function IsValidStructure.

Stack API > SNMP > Internal Members > IsValidStructure Function


OIDLookup Function

Contents | Index | Home
Previous | Up | Next
OIDLookup Function
C
BYTE OIDLookup(
    PDU_INFO* pduDbPtr,
    BYTE* oid,
    BYTE oidLen,
    OID_INFO* rec
);
Stack API > SNMP > Internal Members > OIDLookup Function


ProcessGetSetHeader Function

Contents | Index | Home
Previous | Up | Next
ProcessGetSetHeader Function
C
static BOOL ProcessGetSetHeader(
    PDU_INFO* pduDbPtr
);
Description

All the variables of snmp pdu request header are validated for their data types. Collects request_id for the snmp request pdu. Fetch,validates error status,error index and discard as they are need not to be processed as received in request pdu. Collects non repeaters and max repeaters values in case of Get_Bulk request.

Preconditions

ProcessHeader() is called and returns pdu type and do not returns SNMP_ACTION_UNKNOWN

Parameters
Parameters | Description
pduDbPtr | Pointer to received pdu information database.
Return Values
Return Values | Description
TRUE | If the received request header is validated and passed.
FALSE | If rxed request header is not valid.
Remarks

The request pdu will be processed only if this routine returns TRUE

Stack API > SNMP > Internal Members > ProcessGetSetHeader Function


ProcessHeader Function

Contents | Index | Home
Previous | Up | Next
ProcessHeader Function
C
static SNMP_ACTION ProcessHeader(
    PDU_INFO* pduDbPtr,
    char* community,
    BYTE* len
);
Description

Collects PDU_INFO (SNMP pdu information database),community name, community length and length of data payload. This function validates the received udp packet for these different variables of snmp pdu. The sequence in which these elements are received is important. The validation is done for the agent processing capabilities and the max UDP packet length as UDP packets can not be fragmented.

Preconditions

UDPIsGetReady(SNMPAgentSocket) is called in SNMPTask(), it check if there is any packet on SNMP Agent socket, should return TRUE.

Parameters
Parameters | Description
pduDbPtr | Pointer to received pdu information database
community | Pointer to var storing, community string in rxed pdu
len | Pointer to var storing, community string length rxed in pdu
Return Values
Return Values | Description
SNMP_ACTION | Snmp request pdu type.
Remarks

The received pdu will be processed only if this routine returns the pdu type else the pdu is discarded as not Snmp pdu.

Stack API > SNMP > Internal Members > ProcessHeader Function


ProcessSetVar Function

Contents | Index | Home
Previous | Up | Next
ProcessSetVar Function
C
BYTE ProcessSetVar(
    PDU_INFO* pduDbPtr,
    OID_INFO* rec,
    SNMP_ERR_STATUS* errorStatus
);
Description

This is function ProcessSetVar.

Stack API > SNMP > Internal Members > ProcessSetVar Function


ProcessVariables Function

Contents | Index | Home
Previous | Up | Next
ProcessVariables Function
C
static BOOL ProcessVariables(
    PDU_INFO* pduDbPtr,
    char* community,
    BYTE len
);
Description

Once the received pdu is validated as Snmp pdu, it is forwarded for processing to this routine. This rotuine handles Get, Get_Next, Get_Bulk, Set request and creates appropriate response as Get_Response. This routine will decide on whether the request pdu should be processed or be discarded.

Preconditions

The received udp packet is varified as SNMP request. ProcessHeader() and ProcessGetSetHeader() returns but FALSE.

Parameters
Parameters | Description
pduDbPtr | Pointer to received pdu information database
community | Pointer to var, storing community string in rxed pdu
len | Pointer to var, storing community string length rxed in pdu
Return Values
Return Values | Description
TRUE | If the snmp request processing is successful.
FALSE | If the processing failed else the processing is not completed.
Remarks

None

Stack API > SNMP > Internal Members > ProcessVariables Function


ReadMIBRecord Function

Contents | Index | Home
Previous | Up | Next
ReadMIBRecord Function
C
static void ReadMIBRecord(
    DWORD h,
    OID_INFO* rec
);
Description

This is function ReadMIBRecord.

Stack API > SNMP > Internal Members > ReadMIBRecord Function


SNMPCheckIfPvtMibObjRequested Function

Contents | Index | Home
Previous | Up | Next
SNMPCheckIfPvtMibObjRequested Function
C
static BOOL SNMPCheckIfPvtMibObjRequested(
    BYTE* OIDValuePtr
);
Stack API > SNMP > Internal Members > SNMPCheckIfPvtMibObjRequested Function


SNMP Stack Members

Contents | Index | Home
Previous | Up | Next
SNMP Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
SNMPInit | Initialize SNMP module internals.
SNMPTask | Polls for every snmp pdu received.
Module

SNMP

Stack API > SNMP > Stack Members


SNMPInit Function

Contents | Index | Home
Previous | Up | Next
SNMPInit Function
C
void SNMPInit();
Description

This function initializes the Snmp agent. One udp socket is intialized and opened at port 161. Agent will receive and transmit all the snmp pdus on this udp socket.

Preconditions

At least one UDP socket must be available. UDPInit() is already called.

Returns

None

Remarks

This function is called only once during lifetime of the application. One UDP socket will be used.

Stack API > SNMP > Stack Members > SNMPInit Function


SNMPTask Function

Contents | Index | Home
Previous | Up | Next
SNMPTask Function
C
BOOL SNMPTask();
Description

Handle incoming SNMP requests as well as any outgoing SNMP responses and timeout conditions.

Preconditions

SNMPInit() is already called.

Return Values
Return Values | Description
TRUE | If SNMP module has finished with a state
FALSE | If a state has not been finished.
Remarks

None

Stack API > SNMP > Stack Members > SNMPTask Function


Functions

Contents | Index | Home
Previous | Up | Next
Functions
Functions
Name | Description
getSnmpV2GenTrapOid | Resolves generic trap code to generic trap OID.
ProcessGetBulkVar | This is function ProcessGetBulkVar.
ProcessGetNextVar | This is function ProcessGetNextVar.
ProcessGetVar | This is function ProcessGetVar.
ProcessSnmpv3MsgData | This is function ProcessSnmpv3MsgData.
SNMPGetExactIndex | To search for exact index node in case of a Sequence variable.
SNMPIdRecrdValidation | Used to Restrict the access dynamic and non dynamic OID string for A perticular SNMP Version.
SNMPIsValidSetLen | Validates the set variable data length to data type.
Snmpv3AESDecryptRxedScopedPdu | This is function Snmpv3AESDecryptRxedScopedPdu.
Snmpv3BufferPut | This is function Snmpv3BufferPut.
Snmpv3FormulateEngineID | This is function Snmpv3FormulateEngineID.
Snmpv3GetAuthEngineTime | This is function Snmpv3GetAuthEngineTime.
Snmpv3GetBufferData | This is function Snmpv3GetBufferData.
Snmpv3InitializeUserDataBase | This is function Snmpv3InitializeUserDataBase.
Snmpv3MsgProcessingModelProcessPDU | This is function Snmpv3MsgProcessingModelProcessPDU.
Snmpv3Notify | This is function Snmpv3Notify.
Snmpv3ScopedPduProcessing | This is function Snmpv3ScopedPduProcessing.
Snmpv3TrapScopedpdu | This is function Snmpv3TrapScopedpdu.
Snmpv3UserSecurityModelProcessPDU | This is function Snmpv3UserSecurityModelProcessPDU.
Snmpv3UsmAesEncryptDecryptInitVector | This is function Snmpv3UsmAesEncryptDecryptInitVector.
Snmpv3UsmOutMsgAuthenticationParam | This is function Snmpv3UsmOutMsgAuthenticationParam.
Snmpv3ValidateEngineId | This is function Snmpv3ValidateEngineId.
Snmpv3ValidateSecNameAndSecLvl | This is function Snmpv3ValidateSecNameAndSecLvl.
Snmpv3ValidateSecurityName | This is function Snmpv3ValidateSecurityName.
Module

SNMP

Stack API > SNMP > Functions


getSnmpV2GenTrapOid Function

Contents | Index | Home
Previous | Up | Next
getSnmpV2GenTrapOid Function
C
BYTE * getSnmpV2GenTrapOid(
    BYTE generic_trap_code,
    BYTE * len
);
Description

This function resolves given generic trap code to generic trap OID.

Preconditions

SNMPNotifyPrepare() is already called.

Parameters
Parameters | Description
generic_trap_code | GENERIC_TRAP_NOTIFICATION_TYPE
len | generic trap OID length
Return Values
Return Values | Description
BYTE * | TRAP OID
Remarks

This would fail if generic_trap_code is not coming under GENERIC_TRAP_NOTIFICATION_TYPE

Stack API > SNMP > Functions > getSnmpV2GenTrapOid Function


ProcessGetBulkVar Function

Contents | Index | Home
Previous | Up | Next
ProcessGetBulkVar Function
C
BYTE ProcessGetBulkVar(
    OID_INFO* rec,
    BYTE* oidValuePtr,
    BYTE* oidLenPtr,
    BYTE* successor,
    PDU_INFO* pduDbPtr
);
Description

This is function ProcessGetBulkVar.

Stack API > SNMP > Functions > ProcessGetBulkVar Function


ProcessGetNextVar Function

Contents | Index | Home
Previous | Up | Next
ProcessGetNextVar Function
C
BYTE ProcessGetNextVar(
    OID_INFO* rec,
    PDU_INFO* pduDbPtr
);
Description

This is function ProcessGetNextVar.

Stack API > SNMP > Functions > ProcessGetNextVar Function


ProcessGetVar Function

Contents | Index | Home
Previous | Up | Next
ProcessGetVar Function
C
BYTE ProcessGetVar(
    OID_INFO* rec,
    BOOL bAsOID,
    PDU_INFO* pduDbPtr
);
Description

This is function ProcessGetVar.

Stack API > SNMP > Functions > ProcessGetVar Function


ProcessSnmpv3MsgData Function

Contents | Index | Home
Previous | Up | Next
ProcessSnmpv3MsgData Function
C
BOOL ProcessSnmpv3MsgData(
    PDU_INFO* pduDbPtr
);
Description

This is function ProcessSnmpv3MsgData.

Stack API > SNMP > Functions > ProcessSnmpv3MsgData Function


SNMPGetExactIndex Function

Contents | Index | Home
Previous | Up | Next
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.

Stack API > SNMP > Functions > SNMPGetExactIndex Function


SNMPIdRecrdValidation Function

Contents | Index | Home
Previous | Up | Next
SNMPIdRecrdValidation Function
C
BOOL SNMPIdRecrdValidation(
    PDU_INFO * pduPtr,
    OID_INFO * var,
    BYTE * oidValuePtr,
    BYTE oidLen
);
Description

This is a callback function called by SNMP module. SNMP user must implement this function as per SNMP version. One need to add the new SNMP MIB IDs hereas per SNMP version. e.g - SYS_UP_TIME (250) is common for V1/V2/V3 ENGINE_ID - is the part of V3, So put the all the SNMPv3 var ids within Macro STACK_USE_SNMPV3_SERVER.

Preconditions

None

Parameters
Parameters | Description
var | Variable rec whose record id need to be validated
oidValuePtr | OID Value
oidLen | oidValuePtr length
Return Values
Return Values | Description
TRUE | If a Var ID exists .
FALSE | Otherwise.
Remarks

None.

Stack API > SNMP > Functions > SNMPIdRecrdValidation Function


SNMPIsValidSetLen Function

Contents | Index | Home
Previous | Up | Next
SNMPIsValidSetLen Function
C
BOOL SNMPIsValidSetLen(
    SNMP_ID var,
    BYTE len,
    BYTE index
);
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

ProcessSetVar() is called.

Parameters
Parameters | Description
var | Variable id whose value is to be set
len | Length value that is to be validated.
index | instance of a OID
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)

Stack API > SNMP > Functions > SNMPIsValidSetLen Function


Snmpv3AESDecryptRxedScopedPdu Function

Contents | Index | Home
Previous | Up | Next
Snmpv3AESDecryptRxedScopedPdu Function
C
BYTE Snmpv3AESDecryptRxedScopedPdu();
Description

This is function Snmpv3AESDecryptRxedScopedPdu.

Stack API > SNMP > Functions > Snmpv3AESDecryptRxedScopedPdu Function


Snmpv3BufferPut Function

Contents | Index | Home
Previous | Up | Next
Snmpv3BufferPut Function
C
BOOL Snmpv3BufferPut(
    BYTE val,
    SNMPV3MSGDATA * putbuf
);
Description

This is function Snmpv3BufferPut.

Stack API > SNMP > Functions > Snmpv3BufferPut Function


Snmpv3FormulateEngineID Function

Contents | Index | Home
Previous | Up | Next
Snmpv3FormulateEngineID Function
C
void Snmpv3FormulateEngineID(
    UINT8 fifthOctectIdentifier
);
Description

This is function Snmpv3FormulateEngineID.

Stack API > SNMP > Functions > Snmpv3FormulateEngineID Function


Snmpv3GetAuthEngineTime Function

Contents | Index | Home
Previous | Up | Next
Snmpv3GetAuthEngineTime Function
C
void Snmpv3GetAuthEngineTime();
Description

This is function Snmpv3GetAuthEngineTime.

Stack API > SNMP > Functions > Snmpv3GetAuthEngineTime Function


Snmpv3GetBufferData Function

Contents | Index | Home
Previous | Up | Next
Snmpv3GetBufferData Function
C
BYTE Snmpv3GetBufferData(
    SNMPV3MSGDATA getbuf,
    UINT16 pos
);
Description

This is function Snmpv3GetBufferData.

Stack API > SNMP > Functions > Snmpv3GetBufferData Function


Snmpv3InitializeUserDataBase Function

Contents | Index | Home
Previous | Up | Next
Snmpv3InitializeUserDataBase Function
C
void Snmpv3InitializeUserDataBase();
Description

This is function Snmpv3InitializeUserDataBase.

Stack API > SNMP > Functions > Snmpv3InitializeUserDataBase Function


Snmpv3MsgProcessingModelProcessPDU Function

Contents | Index | Home
Previous | Up | Next
Snmpv3MsgProcessingModelProcessPDU Function
C
SNMP_ACTION Snmpv3MsgProcessingModelProcessPDU(
    BYTE inOutPdu
);
Description

This is function Snmpv3MsgProcessingModelProcessPDU.

Stack API > SNMP > Functions > Snmpv3MsgProcessingModelProcessPDU Function


Snmpv3Notify Function

Contents | Index | Home
Previous | Up | Next
Snmpv3Notify Function
C
BOOL Snmpv3Notify(
    SNMP_ID var,
    SNMP_VAL val,
    SNMP_INDEX index,
    UINT8 targetIndex
);
Description

This is function Snmpv3Notify.

Stack API > SNMP > Functions > Snmpv3Notify Function


Snmpv3ScopedPduProcessing Function

Contents | Index | Home
Previous | Up | Next
Snmpv3ScopedPduProcessing Function
C
SNMP_ACTION Snmpv3ScopedPduProcessing(
    BYTE inOutPdu
);
Description

This is function Snmpv3ScopedPduProcessing.

Stack API > SNMP > Functions > Snmpv3ScopedPduProcessing Function


Snmpv3TrapScopedpdu Function

Contents | Index | Home
Previous | Up | Next
Snmpv3TrapScopedpdu Function
C
UINT8 Snmpv3TrapScopedpdu(
    SNMP_ID var,
    SNMP_VAL val,
    SNMP_INDEX index,
    UINT8 targetIndex
);
Description

This is function Snmpv3TrapScopedpdu.

Stack API > SNMP > Functions > Snmpv3TrapScopedpdu Function


Snmpv3UserSecurityModelProcessPDU Function

Contents | Index | Home
Previous | Up | Next
Snmpv3UserSecurityModelProcessPDU Function
C
SNMP_ACTION Snmpv3UserSecurityModelProcessPDU(
    BYTE inOutPdu
);
Description

This is function Snmpv3UserSecurityModelProcessPDU.

Stack API > SNMP > Functions > Snmpv3UserSecurityModelProcessPDU Function


Snmpv3UsmAesEncryptDecryptInitVector Function

Contents | Index | Home
Previous | Up | Next
Snmpv3UsmAesEncryptDecryptInitVector Function
C
void Snmpv3UsmAesEncryptDecryptInitVector(
    BYTE inOutPdu
);
Description

This is function Snmpv3UsmAesEncryptDecryptInitVector.

Stack API > SNMP > Functions > Snmpv3UsmAesEncryptDecryptInitVector Function


Snmpv3UsmOutMsgAuthenticationParam Function

Contents | Index | Home
Previous | Up | Next
Snmpv3UsmOutMsgAuthenticationParam Function
C
void Snmpv3UsmOutMsgAuthenticationParam(
    UINT8 hashType
);
Description

This is function Snmpv3UsmOutMsgAuthenticationParam.

Stack API > SNMP > Functions > Snmpv3UsmOutMsgAuthenticationParam Function


Snmpv3ValidateEngineId Function

Contents | Index | Home
Previous | Up | Next
Snmpv3ValidateEngineId Function
C
BOOL Snmpv3ValidateEngineId();
Description

This is function Snmpv3ValidateEngineId.

Stack API > SNMP > Functions > Snmpv3ValidateEngineId Function


Snmpv3ValidateSecNameAndSecLvl Function

Contents | Index | Home
Previous | Up | Next
Snmpv3ValidateSecNameAndSecLvl Function
C
BOOL Snmpv3ValidateSecNameAndSecLvl();
Description

This is function Snmpv3ValidateSecNameAndSecLvl.

Stack API > SNMP > Functions > Snmpv3ValidateSecNameAndSecLvl Function


Snmpv3ValidateSecurityName Function

Contents | Index | Home
Previous | Up | Next
Snmpv3ValidateSecurityName Function
C
BOOL Snmpv3ValidateSecurityName();
Description

This is function Snmpv3ValidateSecurityName.

Stack API > SNMP > Functions > Snmpv3ValidateSecurityName Function


Types

Contents | Index | Home
Previous | Up | Next
Types
Enumerations
Name | Description
INOUT_SNMP_PDU | This is type INOUT_SNMP_PDU.
Module

SNMP

Structures
Name | Description
SNMPNONMIBRECDINFO | This is type SNMPNONMIBRECDINFO.
SNMPV3MSGDATA | SNMPv3
Stack API > SNMP > Types


INOUT_SNMP_PDU Enumeration

Contents | Index | Home
Previous | Up | Next
INOUT_SNMP_PDU Enumeration
C
typedef enum {
  SNMP_RESPONSE_PDU = 0x01,
  SNMP_REQUEST_PDU = 0x02
} INOUT_SNMP_PDU;
Description

This is type INOUT_SNMP_PDU.

Stack API > SNMP > Types > INOUT_SNMP_PDU Enumeration


SNMPNONMIBRECDINFO Structure

Contents | Index | Home
Previous | Up | Next
SNMPNONMIBRECDINFO Structure
C
typedef struct {
  UINT8 oidstr[16];
  UINT8 version;
} SNMPNONMIBRECDINFO;
Description

This is type SNMPNONMIBRECDINFO.

Stack API > SNMP > Types > SNMPNONMIBRECDINFO Structure


SNMPV3MSGDATA Structure

Contents | Index | Home
Previous | Up | Next
SNMPV3MSGDATA Structure
C
typedef struct {
  UINT8 * head;
  WORD length;
  WORD maxlength;
  WORD msgAuthParamOffset;
} SNMPV3MSGDATA;
Description

SNMPv3

Stack API > SNMP > Types > SNMPV3MSGDATA Structure


Variables

Contents | Index | Home
Previous | Up | Next
Variables
Module

SNMP

Variables
Name | Description
getZeroInstance | This variable is used for gext next request for zero instance
gSNMPv3ScopedPduDataPos | This is variable gSNMPv3ScopedPduDataPos.
gSNMPv3ScopedPduRequestBuf | This is variable gSNMPv3ScopedPduRequestBuf.
gSNMPv3ScopedPduResponseBuf | This is variable gSNMPv3ScopedPduResponseBuf.
msgSecrtyParamLenOffset | This is variable msgSecrtyParamLenOffset.
Stack API > SNMP > Variables


getZeroInstance Variable

Contents | Index | Home
Previous | Up | Next
getZeroInstance Variable
C
BOOL getZeroInstance;
Description

This variable is used for gext next request for zero instance

Stack API > SNMP > Variables > getZeroInstance Variable


gSNMPv3ScopedPduDataPos Variable

Contents | Index | Home
Previous | Up | Next
gSNMPv3ScopedPduDataPos Variable
C
UINT16 gSNMPv3ScopedPduDataPos;
Description

This is variable gSNMPv3ScopedPduDataPos.

Stack API > SNMP > Variables > gSNMPv3ScopedPduDataPos Variable


gSNMPv3ScopedPduRequestBuf Variable

Contents | Index | Home
Previous | Up | Next
gSNMPv3ScopedPduRequestBuf Variable
C
SNMPV3MSGDATA gSNMPv3ScopedPduRequestBuf;
Description

This is variable gSNMPv3ScopedPduRequestBuf.

Stack API > SNMP > Variables > gSNMPv3ScopedPduRequestBuf Variable


gSNMPv3ScopedPduResponseBuf Variable

Contents | Index | Home
Previous | Up | Next
gSNMPv3ScopedPduResponseBuf Variable
C
SNMPV3MSGDATA gSNMPv3ScopedPduResponseBuf;
Description

This is variable gSNMPv3ScopedPduResponseBuf.

Stack API > SNMP > Variables > gSNMPv3ScopedPduResponseBuf Variable


msgSecrtyParamLenOffset Variable

Contents | Index | Home
Previous | Up | Next
msgSecrtyParamLenOffset Variable
C
WORD msgSecrtyParamLenOffset;
Description

This is variable msgSecrtyParamLenOffset.

Stack API > SNMP > Variables > msgSecrtyParamLenOffset Variable


Macros

Contents | Index | Home
Previous | Up | Next
Macros
Macros
Name | Description
IS_SNMPV3_AUTH_STRUCTURE | This is macro IS_SNMPV3_AUTH_STRUCTURE.
REPORT_RESPONSE | This is macro REPORT_RESPONSE.
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_V3 | This is macro SNMP_V3.
Module

SNMP

Stack API > SNMP > Macros


IS_SNMPV3_AUTH_STRUCTURE Macro

Contents | Index | Home
Previous | Up | Next
IS_SNMPV3_AUTH_STRUCTURE Macro
C
#define IS_SNMPV3_AUTH_STRUCTURE(a) (a==SNMPV3_ENCRYPTION)
Description

This is macro IS_SNMPV3_AUTH_STRUCTURE.

Stack API > SNMP > Macros > IS_SNMPV3_AUTH_STRUCTURE Macro


REPORT_RESPONSE Macro

Contents | Index | Home
Previous | Up | Next
REPORT_RESPONSE Macro
C
#define REPORT_RESPONSE (0xa8)
Description

This is macro REPORT_RESPONSE.

Stack API > SNMP > Macros > REPORT_RESPONSE Macro


SNMP_MAX_MSG_SIZE Macro

Contents | Index | Home
Previous | Up | Next
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.

Stack API > SNMP > Macros > SNMP_MAX_MSG_SIZE Macro


SNMP_V3 Macro

Contents | Index | Home
Previous | Up | Next
SNMP_V3 Macro
C
#define SNMP_V3 (3)
Description

This is macro SNMP_V3.

Stack API > SNMP > Macros > SNMP_V3 Macro


SNTP Client

Contents | Index | Home
Previous | Up | Next
SNTP Client

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 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 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.

Topics
Name | Description
SNTP Client Public Members | Functions and variables accessible by the stack application
SNTP Client Stack Members | Functions and variables intended to be accessed only by the stack
SNTP Client Internal Members | Functions and variables internal to the SNTP Client module
Stack API > SNTP Client


SNTP Client Public Members

Contents | Index | Home
Previous | Up | Next
SNTP Client Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
SNTPGetUTCSeconds | Obtains the current time from the SNTP module.
Module

SNTP Client

Stack API > SNTP Client > Public Members


SNTPGetUTCSeconds Function

Contents | Index | Home
Previous | Up | Next
SNTPGetUTCSeconds Function
C
DWORD SNTPGetUTCSeconds();
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

None

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.

Stack API > SNTP Client > Public Members > SNTPGetUTCSeconds Function


SNTP Client Stack Members

Contents | Index | Home
Previous | Up | Next
SNTP Client Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
SNTPClient | Periodically checks the current time from a pool of servers.
Module

SNTP Client

Stack API > SNTP Client > Stack Members


SNTPClient Function

Contents | Index | Home
Previous | Up | Next
SNTPClient Function
C
void SNTPClient();
Description

This function periodically checks a pool of time servers to obtain the current date/time.

Preconditions

UDP is initialized.

Returns

None

Remarks

This function requires once available UDP socket while processing, but frees that socket when the SNTP module is idle.

Stack API > SNTP Client > Stack Members > SNTPClient Function


SNTP Client Internal Members

Contents | Index | Home
Previous | Up | Next
SNTP Client Internal Members

The following functions and variables are designated as internal to the SNTP Client module.

Macros
Name | Description
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. Updates may take up to 6 seconds to fail, so this 14 second delay is actually only an 8-second retry.
NTP_QUERY_INTERVAL | Defines how frequently to resynchronize the date/time (default: 10 minutes)
NTP_REPLY_TIMEOUT | Defines how long to wait before assuming the query has failed
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
Module

SNTP Client

Structures
Name | Description
NTP_PACKET | Defines the structure of an NTP packet
Variables
Name | Description
dwLastUpdateTick | Tick count of last update
dwSNTPSeconds | Seconds value obtained by last update
Stack API > SNTP Client > Internal Members


NTP_PACKET Structure

Contents | Index | Home
Previous | Up | Next
NTP_PACKET Structure
C
typedef struct {
  struct {
    BYTE mode : 3;
    BYTE versionNumber : 3;
    BYTE leapIndicator : 2;
  } flags;
  BYTE stratum;
  CHAR poll;
  CHAR precision;
  DWORD root_delay;
  DWORD root_dispersion;
  DWORD ref_identifier;
  DWORD ref_ts_secs;
  DWORD ref_ts_fraq;
  DWORD orig_ts_secs;
  DWORD orig_ts_fraq;
  DWORD recv_ts_secs;
  DWORD recv_ts_fraq;
  DWORD tx_ts_secs;
  DWORD tx_ts_fraq;
} NTP_PACKET;
Description

Defines the structure of an NTP packet

Members
Members
Description
struct {
BYTE mode : 3;
BYTE versionNumber : 3;
BYTE leapIndicator : 2;
} flags;
Flags for the packet
BYTE mode : 3;
NTP mode
BYTE versionNumber : 3;
SNTP version number
BYTE leapIndicator : 2;
Leap second indicator
BYTE stratum;
Stratum level of local clock
CHAR poll;
Poll interval
CHAR precision;
Precision (seconds to nearest power of 2)
DWORD root_delay;
Root delay between local machine and server
DWORD root_dispersion;
Root dispersion (maximum error)
DWORD ref_identifier;
Reference clock identifier
DWORD ref_ts_secs;
Reference timestamp (in seconds)
DWORD ref_ts_fraq;
Reference timestamp (fractions)
DWORD orig_ts_secs;
Origination timestamp (in seconds)
DWORD orig_ts_fraq;
Origination timestamp (fractions)
DWORD recv_ts_secs;
Time at which request arrived at sender (seconds)
DWORD recv_ts_fraq;
Time at which request arrived at sender (fractions)
DWORD tx_ts_secs;
Time at which request left sender (seconds)
DWORD tx_ts_fraq;
Time at which request left sender (fractions)
Stack API > SNTP Client > Internal Members > NTP_PACKET Structure


dwLastUpdateTick Variable

Contents | Index | Home
Previous | Up | Next
dwLastUpdateTick Variable
C
DWORD dwLastUpdateTick = 0;
Description

Tick count of last update

Stack API > SNTP Client > Internal Members > dwLastUpdateTick Variable


dwSNTPSeconds Variable

Contents | Index | Home
Previous | Up | Next
dwSNTPSeconds Variable
C
DWORD dwSNTPSeconds = 0;
Description

Seconds value obtained by last update

Stack API > SNTP Client > Internal Members > dwSNTPSeconds Variable


NTP_EPOCH Macro

Contents | Index | Home
Previous | Up | Next
NTP_EPOCH Macro
C
#define NTP_EPOCH (86400ul * (365ul * 70ul + 17ul))
Description

Reference Epoch to use. (default: 01-Jan-1970 00:00:00)

Stack API > SNTP Client > Internal Members > NTP_EPOCH Macro


NTP_FAST_QUERY_INTERVAL Macro

Contents | Index | Home
Previous | Up | Next
NTP_FAST_QUERY_INTERVAL Macro
C
#define NTP_FAST_QUERY_INTERVAL (14ull * TICK_SECOND)
Description

Defines how long to wait to retry an update after a failure. Updates may take up to 6 seconds to fail, so this 14 second delay is actually only an 8-second retry.

Stack API > SNTP Client > Internal Members > NTP_FAST_QUERY_INTERVAL Macro


NTP_QUERY_INTERVAL Macro

Contents | Index | Home
Previous | Up | Next
NTP_QUERY_INTERVAL Macro
C
#define NTP_QUERY_INTERVAL (10ull*60ull * TICK_SECOND)
Description

Defines how frequently to resynchronize the date/time (default: 10 minutes)

Stack API > SNTP Client > Internal Members > NTP_QUERY_INTERVAL Macro


NTP_REPLY_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
NTP_REPLY_TIMEOUT Macro
C
#define NTP_REPLY_TIMEOUT (6ul*TICK_SECOND)
Description

Defines how long to wait before assuming the query has failed

Stack API > SNTP Client > Internal Members > NTP_REPLY_TIMEOUT Macro


NTP_SERVER Macro

Contents | Index | Home
Previous | Up | Next
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.

Stack API > SNTP Client > Internal Members > NTP_SERVER Macro


NTP_SERVER_PORT Macro

Contents | Index | Home
Previous | Up | Next
NTP_SERVER_PORT Macro
C
#define NTP_SERVER_PORT (123ul)
Description

Port for contacting NTP servers

Stack API > SNTP Client > Internal Members > NTP_SERVER_PORT Macro


SSL

Contents | Index | Home
Previous | Up | Next
SSL

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.

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 [image] http://www.microchipdirect.com/productsearch.aspx?Keywords=SW300052.

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.

Once the handshake has started, call TCPSSLIsHandshaking 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 called UseSSL. That field controls whether or not the SMTP client module will attempt to make an SSL connection before transmitting any data.

SSL Server Support

To initiate an SSL server, first open a TCP socket for listening using TCPOpen. Then call TCPAddSSLListener to listen for incoming SSL connections on an alternate port. This allows a single socket to share application-level resources and listen 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 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.

SSL server support is automatically enabled for HTTP2 when STACK_USE_SSL_SERVER is defined. By default, the HTTP2 module will then listen for unsecured traffic on port 80 and secured connections on port 443.

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 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.

Topics
Name | Description
Generating Server Certificates | Describes how to import an SSL certificate into your code.
SSL Public Members | Functions and variables accessible by the stack application
SSL Stack Members | Functions and variables intended to be accessed only by the stack
SSL Internal Members | Functions and variables internal to the SSL module
Stack API > SSL


Generating Server Certificates

Contents | Index | Home
Previous | Up | Next
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.
  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 [image] 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, 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.
Module

SSL

Stack API > SSL > Generating Server Certificates


SSL Public Members

Contents | Index | Home
Previous | Up | Next
SSL Public Members

The following functions and variables are available to the stack application.

Enumerations
Name | Description
SSL_SUPPLEMENTARY_DATA_TYPES | This is type SSL_SUPPLEMENTARY_DATA_TYPES.
Functions
Name | Description
TCPAddSSLListener | Listens for SSL connection on a specific port.
TCPSSLIsHandshaking | Determines if an SSL session is still handshaking.
TCPStartSSLClient | Begins an SSL client session.
TCPIsSSL | Determines if a TCP connection is secured with SSL.
SSLStartSession | Begins a new SSL session for the given TCP connection.
Macros
Name | Description
SSL_INVALID_ID | Identifier for invalid SSL allocations
Module

SSL

Structures
Name | Description
SSL_PKEY_INFO | To hash the public key information, we need to actually get the public key information... 1024 bit key at 8 bits/byte = 128 bytes needed for the public key.
Stack API > SSL > Public Members


SSL_INVALID_ID Macro

Contents | Index | Home
Previous | Up | Next
SSL_INVALID_ID Macro
C
#define SSL_INVALID_ID (0xFFu)        // Identifier for invalid SSL allocations
Description

Identifier for invalid SSL allocations

Stack API > SSL > Public Members > SSL_INVALID_ID Macro


TCPAddSSLListener Function

Contents | Index | Home
Previous | Up | Next
TCPAddSSLListener Function
C
BOOL TCPAddSSLListener(
    TCP_SOCKET hTCP,
    WORD 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.
Stack API > SSL > Public Members > TCPAddSSLListener Function


TCPSSLIsHandshaking Function

Contents | Index | Home
Previous | Up | Next
TCPSSLIsHandshaking Function
C
BOOL TCPSSLIsHandshaking(
    TCP_SOCKET hTCP
);
Description

Call this function after calling TCPStartSSLClient 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
Stack API > SSL > Public Members > TCPSSLIsHandshaking Function


TCPStartSSLClient Function

Contents | Index | Home
Previous | Up | Next
TCPStartSSLClient Function
C
BOOL TCPStartSSLClient(
    TCP_SOCKET hTCP,
    BYTE* 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.

Stack API > SSL > Public Members > TCPStartSSLClient Function


TCPIsSSL Function

Contents | Index | Home
Previous | Up | Next
TCPIsSSL Function
C
BOOL TCPIsSSL(
    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
Stack API > SSL > Public Members > TCPIsSSL Function


SSLStartSession Function

Contents | Index | Home
Previous | Up | Next
SSLStartSession Function
C
BYTE SSLStartSession(
    TCP_SOCKET hTCP,
    void * buffer,
    BYTE supDataType
);
Description

Begins a new SSL session for the given TCP connection.

Preconditions

SSL has been initialized and hTCP is connected.

Parameters
Parameters | Description
hTCP | the socket to begin the SSL connection on
buffer | pointer to a supplementary data buffer
supDataType | type of supplementary data to store
Return Values
Return Values | Description
SSL_INVALID_ID | insufficient SSL resources to start a new connection
others | the allocated SSL stub ID
Stack API > SSL > Public Members > SSLStartSession Function


SSL_SUPPLEMENTARY_DATA_TYPES Enumeration

Contents | Index | Home
Previous | Up | Next
SSL_SUPPLEMENTARY_DATA_TYPES Enumeration
C
typedef enum {
  SSL_SUPPLEMENTARY_DATA_NONE = 0,
  SSL_SUPPLEMENTARY_DATA_CERT_PUBLIC_KEY
} SSL_SUPPLEMENTARY_DATA_TYPES;
Description

This is type SSL_SUPPLEMENTARY_DATA_TYPES.

Stack API > SSL > Public Members > SSL_SUPPLEMENTARY_DATA_TYPES Enumeration


SSL_PKEY_INFO Structure

Contents | Index | Home
Previous | Up | Next
SSL_PKEY_INFO Structure
C
typedef struct {
  WORD pub_size_bytes;
  BYTE pub_key[128];
  BYTE pub_e[3];
  BYTE pub_guid;
} SSL_PKEY_INFO;
Description

To hash the public key information, we need to actually get the public key information... 1024 bit key at 8 bits/byte = 128 bytes needed for the public key.

Members
Members | Description
BYTE pub_guid; | This is used as a TCP_SOCKET which is a BYTE
Stack API > SSL > Public Members > SSL_PKEY_INFO Structure


SSL Stack Members

Contents | Index | Home
Previous | Up | Next
SSL Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Enumerations
Name | Description
SSL_STATE | This is type SSL_STATE.
Functions
Name | Description
SSLInit | Initializes the SSL engine.
SSLPeriodic | Performs any periodic tasks for the SSL module.
TCPRequestSSLMessage | Requests an SSL message to be transmitted.
TCPSSLGetPendingTxSize | Determines how many bytes are pending for a future SSL record.
TCPSSLHandleIncoming | Hands newly arrive TCP data to the SSL module for processing.
TCPSSLHandshakeComplete | Clears the SSL handshake flag.
TCPSSLInPlaceMACEncrypt | Encrypts and MACs data in place in the TCP TX buffer.
TCPSSLPutRecordHeader | Writes an SSL record header and sends an SSL record.
TCPStartSSLServer | Begins an SSL server session.
Macros
Name | Description
SSL_MIN_SESSION_LIFETIME | Minimum lifetime for SSL Sessions Sessions cannot be reallocated until this much time has elapsed
SSL_RSA_LIFETIME_EXTENSION | Lifetime extension for RSA operations Sessions lifetime is extended by this amount when an RSA calculation is made
Module

SSL

Stack API > SSL > Stack Members


SSL_STATE Enumeration

Contents | Index | Home
Previous | Up | Next
SSL_STATE Enumeration
C
typedef enum {
  SSL_NONE = 0,
  SSL_HANDSHAKING,
  SSL_ESTABLISHED,
  SSL_CLOSED
} SSL_STATE;
Description

This is type SSL_STATE.

Members
Members | Description
SSL_NONE = 0 | No security is enabled
SSL_HANDSHAKING | Handshake is progressing (no application data allowed)
SSL_ESTABLISHED | Connection is established and secured
SSL_CLOSED | Connection has been closed (no applicaiton data is allowed)
Stack API > SSL > Stack Members > SSL_STATE Enumeration


SSLInit Function

Contents | Index | Home
Previous | Up | Next
SSLInit Function
C
void SSLInit();
Description

Initializes the SSL engine.

Preconditions

None

Returns

None

Remarks

This function is called only one during lifetime of the application.

Stack API > SSL > Stack Members > SSLInit Function


SSLPeriodic Function

Contents | Index | Home
Previous | Up | Next
SSLPeriodic Function
C
void SSLPeriodic(
    TCP_SOCKET hTCP,
    BYTE sslStubID
);
Description

This function performs periodic tasks for the SSL module. This includes processing for RSA operations.

Preconditions

SSL has already been initialized.

Parameters
Parameters | Description
hTCP | the socket for which to perform periodic functions
id | the SSL stub to use
Returns

None

Stack API > SSL > Stack Members > SSLPeriodic Function


TCPRequestSSLMessage Function

Contents | Index | Home
Previous | Up | Next
TCPRequestSSLMessage Function
C
BOOL TCPRequestSSLMessage(
    TCP_SOCKET hTCP,
    BYTE msg
);
Description

This function is called to request that a specific SSL message be transmitted. This message should only be called by the SSL module.

Preconditions

TCP is initialized.

Parameters
Parameters | Description
hTCP | TCP connection to use
msg | One of the SSL_MESSAGE types to transmit.
Return Values
Return Values | Description
TRUE | The message was requested.
FALSE | Another message is already pending transmission.
Stack API > SSL > Stack Members > TCPRequestSSLMessage Function


TCPSSLGetPendingTxSize Function

Contents | Index | Home
Previous | Up | Next
TCPSSLGetPendingTxSize Function
C
WORD TCPSSLGetPendingTxSize(
    TCP_SOCKET hTCP
);
Description

This function determines how many bytes are pending for a future SSL record.

Preconditions

TCP is initialized, and hTCP is connected with an active SSL connection.

Parameters
Parameters | Description
hTCP | TCP connection to check
Returns

None

Stack API > SSL > Stack Members > TCPSSLGetPendingTxSize Function


TCPSSLHandleIncoming Function

Contents | Index | Home
Previous | Up | Next
TCPSSLHandleIncoming Function
C
void TCPSSLHandleIncoming(
    TCP_SOCKET hTCP
);
Description

This function processes incoming TCP data as an SSL record and performs any necessary repositioning and decrypting.

Preconditions

TCP is initialized, and hTCP is connected with an active SSL session.

Parameters
Parameters | Description
hTCP | TCP connection to handle incoming data on
Returns

None

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Stack API > SSL > Stack Members > TCPSSLHandleIncoming Function


TCPSSLHandshakeComplete Function

Contents | Index | Home
Previous | Up | Next
TCPSSLHandshakeComplete Function
C
void TCPSSLHandshakeComplete(
    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
Returns

None

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Stack API > SSL > Stack Members > TCPSSLHandshakeComplete Function


TCPSSLInPlaceMACEncrypt Function

Contents | Index | Home
Previous | Up | Next
TCPSSLInPlaceMACEncrypt Function
C
void TCPSSLInPlaceMACEncrypt(
    TCP_SOCKET hTCP,
    ARCFOUR_CTX* ctx,
    BYTE* MACSecret,
    WORD len
);
Description

This function encrypts data in the TCP buffer while calcuating a MAC. When encryption is finished, the MAC is appended to the buffer and the record will be ready to transmit.

Preconditions

TCP is initialized, hTCP is connected, and ctx's Sbox is loaded.

Parameters
Parameters | Description
hTCP | TCP connection to encrypt in
ctx | ARCFOUR encryption context to use
MACSecret | MAC encryption secret to use
len | Number of bytes to crypt
Returns

None

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Stack API > SSL > Stack Members > TCPSSLInPlaceMACEncrypt Function


TCPSSLPutRecordHeader Function

Contents | Index | Home
Previous | Up | Next
TCPSSLPutRecordHeader Function
C
void TCPSSLPutRecordHeader(
    TCP_SOCKET hTCP,
    BYTE* hdr,
    BOOL recDone
);
Description

This function writes an SSL record header to the pending TCP SSL data, then indicates that the data is ready to be sent by moving the txHead pointer.

If the record is complete, set recDone to TRUE. The sslTxHead pointer will be moved forward 5 bytes to leave space for a future record header. If the record is only partially sent, use FALSE and to leave the pointer where it is so that more data can be added to the record. Partial records can only be used for the SERVER_CERTIFICATE handshake message.

Preconditions

TCP is initialized, and hTCP is connected with an active SSL session.

Parameters
Parameters | Description
hTCP | TCP connection to write the header and transmit with
hdr | Record header (5 bytes) to send or NULL to just move the pointerctx
recDone | TRUE if the record is done, FALSE otherwise
Returns

None

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Stack API > SSL > Stack Members > TCPSSLPutRecordHeader Function


TCPStartSSLServer Function

Contents | Index | Home
Previous | Up | Next
TCPStartSSLServer Function
C
BOOL TCPStartSSLServer(
    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
Stack API > SSL > Stack Members > TCPStartSSLServer Function


SSL_MIN_SESSION_LIFETIME Macro

Contents | Index | Home
Previous | Up | Next
SSL_MIN_SESSION_LIFETIME Macro
C
#define SSL_MIN_SESSION_LIFETIME (1*TICK_SECOND)
Description

Minimum lifetime for SSL Sessions Sessions cannot be reallocated until this much time has elapsed

Stack API > SSL > Stack Members > SSL_MIN_SESSION_LIFETIME Macro


SSL_RSA_LIFETIME_EXTENSION Macro

Contents | Index | Home
Previous | Up | Next
SSL_RSA_LIFETIME_EXTENSION Macro
C
#define SSL_RSA_LIFETIME_EXTENSION (8*TICK_SECOND)
Description

Lifetime extension for RSA operations Sessions lifetime is extended by this amount when an RSA calculation is made

Stack API > SSL > Stack Members > SSL_RSA_LIFETIME_EXTENSION Macro


SSL Internal Members

Contents | Index | Home
Previous | Up | Next
SSL Internal Members

The following functions and variables are designated as internal to the SSL module.

Enumerations
Name | Description
SM_SSL_RX_SERVER_HELLO | State machine for SSLRxServerHello
SSL_ALERT_LEVEL | Describes the two types of Alert records
SSL_MESSAGES | Describes the types of SSL messages (handshake and alerts)
SSL_SESSION_TYPE | SSL Session Type Enumeration
Functions
Name
Description
CalculateFinishedHash
Calculates the handshake hash over the data. hashID can be either MD5 or SHA-1, and this function will calculate accordingly.
GenerateHashRounds
Generates hash rounds to find either the Master Secret or the Key Block.
GenerateSessionKeys
Generates the session write keys and MAC secrets
HSEnd
Hashes the message contents into the Handshake hash structures and begins a new handshake hash.
HSGet
Reads data from socket, transparently hashing it into the handshake hashes.
HSGetArray

  • Function: static WORD HSGetArray(TCP_SOCKET skt, BYTE *data, WORD len)

*

  • PreCondition: None

*

  • Input: skt - socket to read data from
  • data - array to read into, or NULL
  • len - number of bytes to read

*

  • Output: Number of bytes read

*

  • Side Effects: None

*

  • Overview: Reads data from socket, transparently hashing it
  • into the handshake hashes.

*

  • Note: None
HSGetWord
Reads data from socket, transparently hashing it into the handshake hashes.
HSPut
Writes data to socket, transparently hashing it into the handshake hashes.
HSPutArray

  • Function: static WORD HSPutArray(TCP_SOCKET skt, BYTE *data, BYTE len)

*

  • PreCondition: None

*

  • Input: skt - socket to write data to
  • data - data to write
  • len - number of bytes to write

*

  • Output: Number of bytes written

*

  • Side Effects: None

*

  • Overview: Writes data to socket, transparently hashing it
  • into the handshake hashes.

*

  • Note: None
HSPutROMArray
This is function HSPutROMArray.
HSPutWord
Writes data to socket, transparently hashing it into the handshake hashes.
HSStart
Sets up the buffer to store data for handshake hash tracking
LoadOffChip
Copies data from Ethernet RAM to local RAM
SaveOffChip
Copies data in PIC RAM to the Ethernet RAM
SSLBufferAlloc
Allocates a buffer for use.
SSLBufferFree
Specified buffer is released
SSLBufferSync
Specified buffer is loaded to RAM. Only loads if necessary, and saves any current buffer before switching.
SSLHashAlloc
Allocates a hash for use.
SSLHashFree
Specified hash is released
SSLHashSync
Specified hash is loaded to RAM. Only loads if necessary, and saves any current hash before switching.
SSLKeysSync
Specified key set is loaded to RAM. Only loads if necessary, and saves any current key set before switching.
SSLMACAdd
This is function SSLMACAdd.
SSLMACBegin
This is function SSLMACBegin.
SSLMACCalc
This is function SSLMACCalc.
SSLRSAOperation
Pauses connection processing until RSA calculation is complete.
SSLRxAlert
Receives an alert message and decides what to do
SSLRxAntiqueClientHello
Receives the SSLv2 ClientHello message, initiating a new SSL session with a client
SSLRxCCS
Receives a ChangeCipherSpec from the remote server
SSLRxClientHello
Receives the ClientHello message, initiating a new SSL session with a client
SSLRxClientKeyExchange
Receives the ClientKeyExchange message and begins the decryption process.
SSLRxFinished
Receives the Finished message from remote node
SSLRxHandshake
Receives a handshake message.
SSLRxRecord
Receives an SSL record.
SSLRxServerCertificate
Receives ServerCertificate from the remote server, locates the public key information, and executes RSA operation.
SSLRxServerHello
Receives the ServerHello from the remote server
SSLSessionMatchID
Locates a cached SSL session for reuse. Syncs found session into RAM.
SSLSessionMatchIP
Locates a cached SSL session for reuse
SSLSessionNew
Finds space for a new SSL session
SSLSessionSync
Specified session is loaded to RAM. Only loads if necessary, and saves any current session before switching if it has been updated.
SSLStartPartialRecord
Begins a long SSL record.
SSLStubAlloc
Allocates a stub for use.
SSLStubFree
Specified stub is released
SSLStubSync
Specified stub is loaded to RAM. Only loads if necessary, and saves any current stub before switching.
SSLTerminate
Terminates an SSL connection and releases allocated resources.
SSLTxCCSFin
Generates the session keys from the master secret, then allocates and generates the encryption context. Once processing is complete, transmits the Change Cipher Spec message and the Finished handshake message to the server.
SSLTxClientHello
Transmits the ClientHello message to initiate a new SSL session with the server.
SSLTxClientKeyExchange
Transmits the encrypted pre-master secret to the server and requests the Change Cipher Spec. Also generates the Master Secret from the pre-master secret that was used.
SSLTxMessage
Transmits an SSL message.
SSLTxRecord
Transmits an SSL record.
SSLTxServerCertificate
Transmits the Certificate message with the server's specified public key certificate.
SSLTxServerHello
Transmits the ServerHello message.
SSLTxServerHelloDone
Transmits the ServerHelloDone message.
Macros
Name | Description
RESERVED_SSL_MEMORY | Total space needed by all SSL storage requirements
SSL_ALERT | Protocol code for Alert records
SSL_APPLICATION | Protocol code for Application data records
SSL_BASE_BUFFER_ADDR | Base address for SSL buffers
SSL_BASE_HASH_ADDR | Base address for SSL hashes
SSL_BASE_KEYS_ADDR | Base address for SSL keys
SSL_BASE_SESSION_ADDR | Base address for SSL sessions
SSL_BASE_STUB_ADDR | Base address for SSL stubs
SSL_BUFFER_SIZE | Amount of space needed by a single SSL buffer
SSL_BUFFER_SPACE | Amount of space needed by all SSL buffer
SSL_CHANGE_CIPHER_SPEC | Protocol code for Change Cipher Spec records
SSL_HANDSHAKE | Protocol code for Handshake records
SSL_HASH_SIZE | Amount of space needed by a single SSL hash
SSL_HASH_SPACE | Amount of space needed by all SSL hash
SSL_KEYS_SIZE | Amount of space needed by a single SSL key
SSL_KEYS_SPACE | Amount of space needed by all SSL key
SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 | This is macro SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5.
SSL_RSA_WITH_ARCFOUR_128_MD5 | This is macro SSL_RSA_WITH_ARCFOUR_128_MD5.
SSL_SESSION_SIZE | Amount of space needed by a single SSL session
SSL_SESSION_SPACE | Amount of space needed by all SSL session
SSL_STUB_SIZE | Amount of space needed by a single SSL stub
SSL_STUB_SPACE | Amount of space needed by all SSL stubs
SSL_VERSION | SSL version number
SSL_VERSION_HI | SSL version number (high byte)
SSL_VERSION_LO | SSL version number (low byte)
SSLFinishPartialRecord | This is macro SSLFinishPartialRecord.
SSLFlushPartialRecord | This is macro SSLFlushPartialRecord.
SSLSessionUpdated | This is macro SSLSessionUpdated.
Module

SSL

Structures
Name | Description
SSL_KEYS | Memory definition for SSL keys. This area is split into Local and Remote areas. During the handshake, Local.random and Remote.random hold the ServerRandom and ClientRandom values. Once the session keys are calculated, the Local.app and Remote.app contain the MAC secret, record sequence number, and encryption context for the ARCFOUR module.
SSL_SESSION | Storage space for SSL Session identifiers. (The SessionID and MasterSecret)
SSL_SESSION_STUB | Stub value for an SSL_SESSION. The tag associates this session with a remote node, either by matching to a remote IP address when we are the client or the first 3 bytes of the session ID when we are the host. When a session is free/expired, the tag is 0x00000000. The lastUsed value is the Tick count when the session was last used so that older sessions may be overwritten first.
SSL_STUB | Memory holder for general information associated with an SSL connections.
Unions
Name | Description
SSL_BUFFER | Generic buffer space for SSL. The hashRounds element is used when this buffer is needed for handshake hash calculations, and the full element is used as the Sbox for ARCFOUR calculations.
Variables
Name | Description
isBufferUsed | Indicates which buffers are in use
isHashUsed | Indicates which hashes are in use
isStubUsed | Indicates which stubs are in use
masks | Masks for each bit in the is*Used variables
ptrHS | Used in buffering handshake results
SSL_CERT | RSA public certificate data ?
SSL_CERT_LEN | RSA public certificate length ?
sslBufferID | Which buffer is loaded
sslHash | Hash storage
sslHashID | Which hash is loaded
sslKeys | The current SSL session
sslKeysID | Which SSL_KEYS are loaded
sslRSAStubID | Which stub is using RSA, if any
sslSession | Current session data
sslSessionID | Which session is loaded
sslSessionStubs | 8 byte session stubs
sslSessionUpdated | Whether or not it has been updated
sslStub | The current SSL stub
sslStubID | Which SSL_STUB is loaded
Stack API > SSL > Internal Members


CalculateFinishedHash Function

Contents | Index | Home
Previous | Up | Next
CalculateFinishedHash Function
C
static void CalculateFinishedHash(
    BYTE hashID,
    BOOL fromClient,
    BYTE * result
);
Description

Calculates the handshake hash over the data. hashID can be either MD5 or SHA-1, and this function will calculate accordingly.

Preconditions

hashID has all handshake data hashed so far and the current session is synced in.

Parameters
Parameters | Description
hashID | the hash sum to use
fromClient | TRUE if client is sender
result | where to store results
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > CalculateFinishedHash Function


GenerateHashRounds Function

Contents | Index | Home
Previous | Up | Next
GenerateHashRounds Function
C
static void GenerateHashRounds(
    BYTE num,
    BYTE* rand1,
    BYTE* rand2
);
Description

Generates hash rounds to find either the Master Secret or the Key Block.

Preconditions

The SSL buffer is allocated for temporary usage and the data to run rounds on is in sslSession.masterSecret

Parameters
Parameters | Description
num | how many rounds to compute
rand1 | the first random data block to use
rand2 | the second random data block to use
Returns

None

Side Effects

Destroys the SSL Buffer space

Remarks

This function will overflow the buffer after 7 rounds, but in practice num = 3 or num = 4.

Stack API > SSL > Internal Members > GenerateHashRounds Function


GenerateSessionKeys Function

Contents | Index | Home
Previous | Up | Next
GenerateSessionKeys Function
C
static void GenerateSessionKeys();
Description

Generates the session write keys and MAC secrets

Preconditions

The SSL buffer is allocated for temporary usage, session keys are synced, and the TX and RX buffers are allocated for S-boxes.

Returns

None

Side Effects

Destroys the SSL Buffer Space

Remarks

None

Stack API > SSL > Internal Members > GenerateSessionKeys Function


HSEnd Function

Contents | Index | Home
Previous | Up | Next
HSEnd Function
C
static void HSEnd();
Description

Hashes the message contents into the Handshake hash structures and begins a new handshake hash.

Preconditions

None

Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > HSEnd Function


HSGet Function

Contents | Index | Home
Previous | Up | Next
HSGet Function
C
static WORD HSGet(
    TCP_SOCKET skt,
    BYTE * b
);
Description

Reads data from socket, transparently hashing it into the handshake hashes.

Preconditions

None

Parameters
Parameters | Description
skt | socket to read data from
b | byte to read into
Returns

Number of bytes read

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > HSGet Function


HSGetArray Function

Contents | Index | Home
Previous | Up | Next
HSGetArray Function
C
static WORD HSGetArray(
    TCP_SOCKET skt,
    BYTE * data,
    WORD len
);
Description
  • Function: static WORD HSGetArray(TCP_SOCKET skt, BYTE *data, WORD len)

*

  • PreCondition: None

*

  • Input: skt - socket to read data from
  • data - array to read into, or NULL
  • len - number of bytes to read

*

  • Output: Number of bytes read

*

  • Side Effects: None

*

  • Overview: Reads data from socket, transparently hashing it
  • into the handshake hashes.

*

  • Note: None
Stack API > SSL > Internal Members > HSGetArray Function


HSGetWord Function

Contents | Index | Home
Previous | Up | Next
HSGetWord Function
C
static WORD HSGetWord(
    TCP_SOCKET skt,
    WORD * w
);
Description

Reads data from socket, transparently hashing it into the handshake hashes.

Preconditions

None

Parameters
Parameters | Description
skt | socket to read data from
w | word to read into
Returns

Number of bytes read

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > HSGetWord Function


HSPut Function

Contents | Index | Home
Previous | Up | Next
HSPut Function
C
static WORD HSPut(
    TCP_SOCKET skt,
    BYTE b
);
Description

Writes data to socket, transparently hashing it into the handshake hashes.

Preconditions

None

Parameters
Parameters | Description
skt | socket to write data to
b | byte to write
Returns

Number of bytes written

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > HSPut Function


HSPutArray Function

Contents | Index | Home
Previous | Up | Next
HSPutArray Function
C
static WORD HSPutArray(
    TCP_SOCKET skt,
    BYTE * data,
    WORD len
);
Description
  • Function: static WORD HSPutArray(TCP_SOCKET skt, BYTE *data, BYTE len)

*

  • PreCondition: None

*

  • Input: skt - socket to write data to
  • data - data to write
  • len - number of bytes to write

*

  • Output: Number of bytes written

*

  • Side Effects: None

*

  • Overview: Writes data to socket, transparently hashing it
  • into the handshake hashes.

*

  • Note: None
Stack API > SSL > Internal Members > HSPutArray Function


HSPutROMArray Function

Contents | Index | Home
Previous | Up | Next
HSPutROMArray Function
C
static WORD HSPutROMArray(
    TCP_SOCKET skt,
    ROM BYTE * data,
    WORD len
);
Description

This is function HSPutROMArray.

Stack API > SSL > Internal Members > HSPutROMArray Function


HSPutWord Function

Contents | Index | Home
Previous | Up | Next
HSPutWord Function
C
static WORD HSPutWord(
    TCP_SOCKET skt,
    WORD w
);
Description

Writes data to socket, transparently hashing it into the handshake hashes.

Preconditions

None

Parameters
Parameters | Description
skt | socket to write data to
w | word to write
Returns

Number of bytes written

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > HSPutWord Function


HSStart Function

Contents | Index | Home
Previous | Up | Next
HSStart Function
C
static void HSStart();
Description

Sets up the buffer to store data for handshake hash tracking

Preconditions

None

Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > HSStart Function


isBufferUsed Variable

Contents | Index | Home
Previous | Up | Next
isBufferUsed Variable
C
WORD isBufferUsed;
Description

Indicates which buffers are in use

Stack API > SSL > Internal Members > isBufferUsed Variable


isHashUsed Variable

Contents | Index | Home
Previous | Up | Next
isHashUsed Variable
C
WORD isHashUsed;
Description

Indicates which hashes are in use

Stack API > SSL > Internal Members > isHashUsed Variable


isStubUsed Variable

Contents | Index | Home
Previous | Up | Next
isStubUsed Variable
C
WORD isStubUsed;
Description

Indicates which stubs are in use

Stack API > SSL > Internal Members > isStubUsed Variable


masks Variable

Contents | Index | Home
Previous | Up | Next
masks Variable
C
ROM WORD masks[16] = { 0x0001, 0x0002, 0x0004, 0x0008, 0x0010, 0x0020, 0x0040, 0x0080, 0x0100, 0x0200, 0x0400, 0x0800, 0x1000, 0x2000, 0x4000, 0x8000 };
Description

Masks for each bit in the is*Used variables

Stack API > SSL > Internal Members > masks Variable


ptrHS Variable

Contents | Index | Home
Previous | Up | Next
ptrHS Variable
C
BYTE * ptrHS;
Description

Used in buffering handshake results

Stack API > SSL > Internal Members > ptrHS Variable


RESERVED_SSL_MEMORY Macro

Contents | Index | Home
Previous | Up | Next
RESERVED_SSL_MEMORY Macro
C
#define RESERVED_SSL_MEMORY ((DWORD)(SSL_STUB_SPACE + SSL_KEYS_SPACE + SSL_HASH_SPACE + SSL_BUFFER_SPACE + SSL_SESSION_SPACE))
Description

Total space needed by all SSL storage requirements

Stack API > SSL > Internal Members > RESERVED_SSL_MEMORY Macro


LoadOffChip Function

Contents | Index | Home
Previous | Up | Next
LoadOffChip Function
C
static void LoadOffChip(
    BYTE * ramAddr,
    PTR_BASE ethAddr,
    WORD len
);
Description

Copies data from Ethernet RAM to local RAM

Preconditions

None

Parameters
Parameters | Description
ramAddr | destination address in RAM
ethAddr | source address in Ethernet RAM
len | number of bytes to copy
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > LoadOffChip Function


SaveOffChip Function

Contents | Index | Home
Previous | Up | Next
SaveOffChip Function
C
static void SaveOffChip(
    BYTE * ramAddr,
    PTR_BASE ethAddr,
    WORD len
);
Description

Copies data in PIC RAM to the Ethernet RAM

Preconditions

None

Parameters
Parameters | Description
ramAddr | source address in RAM
ethAddr | destination address in Ethernet RAM
len | number of bytes to copy
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SaveOffChip Function


SM_SSL_RX_SERVER_HELLO Enumeration

Contents | Index | Home
Previous | Up | Next
SM_SSL_RX_SERVER_HELLO Enumeration
C
typedef enum {
  RX_SERVER_CERT_START = 0u,
  RX_SERVER_CERT_FIND_KEY,
  RX_SERVER_CERT_FIND_N,
  RX_SERVER_CERT_READ_N,
  RX_SERVER_CERT_READ_E,
  RX_SERVER_CERT_CLEAR
} SM_SSL_RX_SERVER_HELLO;
Description

State machine for SSLRxServerHello

Stack API > SSL > Internal Members > SM_SSL_RX_SERVER_HELLO Enumeration


SSL_ALERT Macro

Contents | Index | Home
Previous | Up | Next
SSL_ALERT Macro
C
#define SSL_ALERT 21u        // Protocol code for Alert records
Description

Protocol code for Alert records

Stack API > SSL > Internal Members > SSL_ALERT Macro


SSL_ALERT_LEVEL Enumeration

Contents | Index | Home
Previous | Up | Next
SSL_ALERT_LEVEL Enumeration
C
typedef enum {
  SSL_ALERT_WARNING = 1u,
  SSL_ALERT_FATAL = 2u
} SSL_ALERT_LEVEL;
Description

Describes the two types of Alert records

Members
Members | Description
SSL_ALERT_WARNING = 1u | Alert message is a warning (session can be resumed)
SSL_ALERT_FATAL = 2u | Alert message is fatal (session is non-resumable)
Stack API > SSL > Internal Members > SSL_ALERT_LEVEL Enumeration


SSL_APPLICATION Macro

Contents | Index | Home
Previous | Up | Next
SSL_APPLICATION Macro
C
#define SSL_APPLICATION 23u        // Protocol code for Application data records
Description

Protocol code for Application data records

Stack API > SSL > Internal Members > SSL_APPLICATION Macro


SSL_BASE_BUFFER_ADDR Macro

Contents | Index | Home
Previous | Up | Next
SSL_BASE_BUFFER_ADDR Macro
C
#define SSL_BASE_BUFFER_ADDR (BASE_SSLB_ADDR + SSL_STUB_SPACE + SSL_KEYS_SPACE + SSL_HASH_SPACE)
Description

Base address for SSL buffers

Stack API > SSL > Internal Members > SSL_BASE_BUFFER_ADDR Macro


SSL_BASE_HASH_ADDR Macro

Contents | Index | Home
Previous | Up | Next
SSL_BASE_HASH_ADDR Macro
C
#define SSL_BASE_HASH_ADDR (BASE_SSLB_ADDR + SSL_STUB_SPACE + SSL_KEYS_SPACE)
Description

Base address for SSL hashes

Stack API > SSL > Internal Members > SSL_BASE_HASH_ADDR Macro


SSL_BASE_KEYS_ADDR Macro

Contents | Index | Home
Previous | Up | Next
SSL_BASE_KEYS_ADDR Macro
C
#define SSL_BASE_KEYS_ADDR (BASE_SSLB_ADDR + SSL_STUB_SPACE)
Description

Base address for SSL keys

Stack API > SSL > Internal Members > SSL_BASE_KEYS_ADDR Macro


SSL_BASE_SESSION_ADDR Macro

Contents | Index | Home
Previous | Up | Next
SSL_BASE_SESSION_ADDR Macro
C
#define SSL_BASE_SESSION_ADDR (BASE_SSLB_ADDR + SSL_STUB_SPACE + SSL_KEYS_SPACE + SSL_HASH_SPACE + SSL_BUFFER_SPACE)
Description

Base address for SSL sessions

Stack API > SSL > Internal Members > SSL_BASE_SESSION_ADDR Macro


SSL_BASE_STUB_ADDR Macro

Contents | Index | Home
Previous | Up | Next
SSL_BASE_STUB_ADDR Macro
C
#define SSL_BASE_STUB_ADDR (BASE_SSLB_ADDR)
Description

Base address for SSL stubs

Stack API > SSL > Internal Members > SSL_BASE_STUB_ADDR Macro


SSL_BUFFER Union

Contents | Index | Home
Previous | Up | Next
SSL_BUFFER Union
C
typedef union {
  struct {
    HASH_SUM hash;
    BYTE md5_hash[16];
    BYTE sha_hash[20];
    BYTE temp[256-sizeof(HASH_SUM)-16-20];
  } hashRounds;
  BYTE full[256];
} SSL_BUFFER;
Description

Generic buffer space for SSL. The hashRounds element is used when this buffer is needed for handshake hash calculations, and the full element is used as the Sbox for ARCFOUR calculations.

Stack API > SSL > Internal Members > SSL_BUFFER Union


SSL_BUFFER_SIZE Macro

Contents | Index | Home
Previous | Up | Next
SSL_BUFFER_SIZE Macro
C
#define SSL_BUFFER_SIZE ((DWORD)sizeof(SSL_BUFFER))                // Amount of space needed by a single SSL buffer
Description

Amount of space needed by a single SSL buffer

Stack API > SSL > Internal Members > SSL_BUFFER_SIZE Macro


SSL_BUFFER_SPACE Macro

Contents | Index | Home
Previous | Up | Next
SSL_BUFFER_SPACE Macro
C
#define SSL_BUFFER_SPACE (SSL_BUFFER_SIZE*MAX_SSL_BUFFERS)        // Amount of space needed by all SSL buffer
Description

Amount of space needed by all SSL buffer

Stack API > SSL > Internal Members > SSL_BUFFER_SPACE Macro


SSL_CERT Variable

Contents | Index | Home
Previous | Up | Next
SSL_CERT Variable
C
ROM BYTE SSL_CERT[];
Description

RSA public certificate data ?

Stack API > SSL > Internal Members > SSL_CERT Variable


SSL_CERT_LEN Variable

Contents | Index | Home
Previous | Up | Next
SSL_CERT_LEN Variable
C
ROM WORD SSL_CERT_LEN;
Description

RSA public certificate length ?

Stack API > SSL > Internal Members > SSL_CERT_LEN Variable


SSL_CHANGE_CIPHER_SPEC Macro

Contents | Index | Home
Previous | Up | Next
SSL_CHANGE_CIPHER_SPEC Macro
C
#define SSL_CHANGE_CIPHER_SPEC 20u        // Protocol code for Change Cipher Spec records
Description

Protocol code for Change Cipher Spec records

Stack API > SSL > Internal Members > SSL_CHANGE_CIPHER_SPEC Macro


SSL_HANDSHAKE Macro

Contents | Index | Home
Previous | Up | Next
SSL_HANDSHAKE Macro
C
#define SSL_HANDSHAKE 22u        // Protocol code for Handshake records
Description

Protocol code for Handshake records

Stack API > SSL > Internal Members > SSL_HANDSHAKE Macro


SSL_HASH_SIZE Macro

Contents | Index | Home
Previous | Up | Next
SSL_HASH_SIZE Macro
C
#define SSL_HASH_SIZE ((DWORD)sizeof(HASH_SUM))                // Amount of space needed by a single SSL hash
Description

Amount of space needed by a single SSL hash

Stack API > SSL > Internal Members > SSL_HASH_SIZE Macro


SSL_HASH_SPACE Macro

Contents | Index | Home
Previous | Up | Next
SSL_HASH_SPACE Macro
C
#define SSL_HASH_SPACE ((DWORD)(SSL_HASH_SIZE*MAX_SSL_HASHES))    // Amount of space needed by all SSL hash
Description

Amount of space needed by all SSL hash

Stack API > SSL > Internal Members > SSL_HASH_SPACE Macro


SSL_KEYS Structure

Contents | Index | Home
Previous | Up | Next
SSL_KEYS Structure
C
typedef struct {
  union {
    struct {
      BYTE MACSecret[16];
      DWORD sequence;
      ARCFOUR_CTX cryptCtx;
      BYTE reserved[8];
    } app;
    BYTE random[32];
  } Local;
  union {
    struct {
      BYTE MACSecret[16];
      DWORD sequence;
      ARCFOUR_CTX cryptCtx;
      BYTE reserved[8];
    } app;
    BYTE random[32];
  } Remote;
} SSL_KEYS;
Description

Memory definition for SSL keys. This area is split into Local and Remote areas. During the handshake, Local.random and Remote.random hold the ServerRandom and ClientRandom values. Once the session keys are calculated, the Local.app and Remote.app contain the MAC secret, record sequence number, and encryption context for the ARCFOUR module.

Members
Members | Description
BYTE MACSecret[16]; | Server's MAC write secret
DWORD sequence; | Server's write sequence number
ARCFOUR_CTX cryptCtx; | Server's write encryption context
BYTE reserved[8]; | Future expansion
BYTE random[32]; | Server.random value
BYTE MACSecret[16]; | Client's MAC write secret
DWORD sequence; | Client's write sequence number
ARCFOUR_CTX cryptCtx; | Client's write encryption context
BYTE reserved[8]; | Future expansion
BYTE random[32]; | Client.random value
Stack API > SSL > Internal Members > SSL_KEYS Structure


SSL_KEYS_SIZE Macro

Contents | Index | Home
Previous | Up | Next
SSL_KEYS_SIZE Macro
C
#define SSL_KEYS_SIZE ((DWORD)sizeof(SSL_KEYS))                // Amount of space needed by a single SSL key
Description

Amount of space needed by a single SSL key

Stack API > SSL > Internal Members > SSL_KEYS_SIZE Macro


SSL_KEYS_SPACE Macro

Contents | Index | Home
Previous | Up | Next
SSL_KEYS_SPACE Macro
C
#define SSL_KEYS_SPACE (SSL_KEYS_SIZE*MAX_SSL_CONNECTIONS)        // Amount of space needed by all SSL key
Description

Amount of space needed by all SSL key

Stack API > SSL > Internal Members > SSL_KEYS_SPACE Macro


SSL_MESSAGES Enumeration

Contents | Index | Home
Previous | Up | Next
SSL_MESSAGES Enumeration
C
typedef enum {
  SSL_HELLO_REQUEST = 0u,
  SSL_CLIENT_HELLO = 1u,
  SSL_ANTIQUE_CLIENT_HELLO = 18u,
  SSL_SERVER_HELLO = 2u,
  SSL_CERTIFICATE = 11u,
  SSL_SERVER_HELLO_DONE = 14u,
  SSL_CLIENT_KEY_EXCHANGE = 16u,
  SSL_FINISHED = 20u,
  SSL_ALERT_CLOSE_NOTIFY = 0u+0x80,
  SSL_ALERT_UNEXPECTED_MESSAGE = 10u+0x80,
  SSL_ALERT_BAD_RECORD_MAC = 20u+0x80,
  SSL_ALERT_HANDSHAKE_FAILURE = 40u+0x80,
  SSL_NO_MESSAGE = 0xff
} SSL_MESSAGES;
Description

Describes the types of SSL messages (handshake and alerts)

Members
Members | Description
SSL_HELLO_REQUEST = 0u | HelloRequest handshake message (not currently supported)
SSL_CLIENT_HELLO = 1u | ClientHello handshake message
SSL_ANTIQUE_CLIENT_HELLO = 18u | SSLv2 ClientHello handshake message (Supported for backwards compatibility. This is an internally defined value.)
SSL_SERVER_HELLO = 2u | ServerHello handshake message
SSL_CERTIFICATE = 11u | ServerCertifiate handshake message
SSL_SERVER_HELLO_DONE = 14u | ServerHelloDone handshake message
SSL_CLIENT_KEY_EXCHANGE = 16u | ClientKeyExchange handshake message
SSL_FINISHED = 20u | Finished handshake message
SSL_ALERT_CLOSE_NOTIFY = 0u+0x80 | CloseNotify alert message (dummy value used internally)
SSL_ALERT_UNEXPECTED_MESSAGE = 10u+0x80 | UnexpectedMessage alert message (dummy value used internally)
SSL_ALERT_BAD_RECORD_MAC = 20u+0x80 | BadRecordMAC alert message (dummy value used internally)
SSL_ALERT_HANDSHAKE_FAILURE = 40u+0x80 | HandshakeFailure alert message (dummy value used internally)
SSL_NO_MESSAGE = 0xff | No message is currently requested (internally used value)
Stack API > SSL > Internal Members > SSL_MESSAGES Enumeration


SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 Macro

Contents | Index | Home
Previous | Up | Next
SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 Macro
C
#define SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 0x0003u
Description

This is macro SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5.

Stack API > SSL > Internal Members > SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 Macro


SSL_RSA_WITH_ARCFOUR_128_MD5 Macro

Contents | Index | Home
Previous | Up | Next
SSL_RSA_WITH_ARCFOUR_128_MD5 Macro
C
#define SSL_RSA_WITH_ARCFOUR_128_MD5 0x0004u
Description

This is macro SSL_RSA_WITH_ARCFOUR_128_MD5.

Stack API > SSL > Internal Members > SSL_RSA_WITH_ARCFOUR_128_MD5 Macro


SSL_SESSION Structure

Contents | Index | Home
Previous | Up | Next
SSL_SESSION Structure
C
typedef struct {
  BYTE sessionID[32];
  BYTE masterSecret[48];
} SSL_SESSION;
Description

Storage space for SSL Session identifiers. (The SessionID and MasterSecret)

Members
Members | Description
BYTE sessionID[32]; | The SSL Session ID for this session
BYTE masterSecret[48]; | Associated Master Secret for this session
Stack API > SSL > Internal Members > SSL_SESSION Structure


SSL_SESSION_SIZE Macro

Contents | Index | Home
Previous | Up | Next
SSL_SESSION_SIZE Macro
C
#define SSL_SESSION_SIZE ((DWORD)sizeof(SSL_SESSION))            // Amount of space needed by a single SSL session
Description

Amount of space needed by a single SSL session

Stack API > SSL > Internal Members > SSL_SESSION_SIZE Macro


SSL_SESSION_SPACE Macro

Contents | Index | Home
Previous | Up | Next
SSL_SESSION_SPACE Macro
C
#define SSL_SESSION_SPACE (SSL_SESSION_SIZE*MAX_SSL_SESSIONS)        // Amount of space needed by all SSL session
Description

Amount of space needed by all SSL session

Stack API > SSL > Internal Members > SSL_SESSION_SPACE Macro


SSL_SESSION_STUB Structure

Contents | Index | Home
Previous | Up | Next
SSL_SESSION_STUB Structure
C
typedef struct {
  DWORD_VAL tag;
  DWORD lastUsed;
} SSL_SESSION_STUB;
Description

Stub value for an SSL_SESSION. The tag associates this session with a remote node, either by matching to a remote IP address when we are the client or the first 3 bytes of the session ID when we are the host. When a session is free/expired, the tag is 0x00000000. The lastUsed value is the Tick count when the session was last used so that older sessions may be overwritten first.

Members
Members | Description
DWORD_VAL tag; | Identifying tag for connection When we're a client, this is the remote IP When we're a host, this is 0x00 followed by first 3 bytes of session ID When this stub is free/expired, this is 0x00
DWORD lastUsed; | Tick count when session was last used
Stack API > SSL > Internal Members > SSL_SESSION_STUB Structure


SSL_SESSION_TYPE Enumeration

Contents | Index | Home
Previous | Up | Next
SSL_SESSION_TYPE Enumeration
C
typedef enum {
  SSL_CLIENT,
  SSL_SERVER
} SSL_SESSION_TYPE;
Description

SSL Session Type Enumeration

Members
Members | Description
SSL_CLIENT | Local device is the SSL client
SSL_SERVER | Local device is the SSL host
Stack API > SSL > Internal Members > SSL_SESSION_TYPE Enumeration


SSL_STUB Structure

Contents | Index | Home
Previous | Up | Next
SSL_STUB Structure
C
typedef struct {
  WORD wRxBytesRem;
  WORD wRxHsBytesRem;
  BYTE rxProtocol;
  BYTE rxHSType;
  BYTE idSession;
  BYTE idMD5, idSHA1;
  BYTE idRxHash;
  BYTE idRxBuffer, idTxBuffer;
  DWORD_VAL dwTemp;
  struct {
    unsigned char bIsServer : 1;
    unsigned char bClientHello : 1;
    unsigned char bServerHello : 1;
    unsigned char bServerCertificate : 1;
    unsigned char bServerHelloDone : 1;
    unsigned char bClientKeyExchange : 1;
    unsigned char bRemoteChangeCipherSpec : 1;
    unsigned char bRemoteFinished : 1;
    unsigned char bLocalChangeCipherSpec : 1;
    unsigned char bLocalFinished : 1;
    unsigned char bExpectingMAC : 1;
    unsigned char bNewSession : 1;
    unsigned char bCloseNotify : 1;
    unsigned char bDone : 1;
    unsigned char bRSAInProgress : 1;
    unsigned char bKeysValid : 1;
  } Flags;
  BYTE requestedMessage;
  void * supplementaryBuffer;
  BYTE supplementaryDataType;
} SSL_STUB;
Description

Memory holder for general information associated with an SSL connections.

Members
Members | Description
WORD wRxBytesRem; | Bytes left to read in current record
WORD wRxHsBytesRem; | Bytes left to read in current Handshake submessage
BYTE rxProtocol; | Protocol for message being read
BYTE rxHSType; | Handshake message being received
BYTE idSession; | ID for associated session
BYTE idRxHash; | ID for MAC hash (TX needs no persistence)
DWORD_VAL dwTemp; | Used for state machine in RxCertificate
unsigned char bIsServer : 1; | We are the server
unsigned char bClientHello : 1; | ClientHello has been sent/received
unsigned char bServerHello : 1; | ServerHello has been sent/received
unsigned char bServerCertificate : 1; | ServerCertificate has been sent/received
unsigned char bServerHelloDone : 1; | ServerHelloDone has been sent/received
unsigned char bClientKeyExchange : 1; | ClientKeyExchange has been sent/received
unsigned char bRemoteChangeCipherSpec : 1; | Remote node has sent a ChangeCipherSpec message
unsigned char bRemoteFinished : 1; | Remote node has sent a Finished message
unsigned char bLocalChangeCipherSpec : 1; | We have sent a ChangeCipherSpec message
unsigned char bLocalFinished : 1; | We have sent a Finished message
unsigned char bExpectingMAC : 1; | We expect a MAC at end of message
unsigned char bNewSession : 1; | TRUE if a new session, FALSE if resuming
unsigned char bCloseNotify : 1; | Whether or not a CloseNotify has been sent/received
unsigned char bDone : 1; | TRUE if the connection is closed
unsigned char bRSAInProgress : 1; | TRUE when RSA op is in progress
unsigned char bKeysValid : 1; | TRUE if the session keys have been generated
BYTE requestedMessage; | Currently requested message to send, or 0xff
Stack API > SSL > Internal Members > SSL_STUB Structure


SSL_STUB_SIZE Macro

Contents | Index | Home
Previous | Up | Next
SSL_STUB_SIZE Macro
C
#define SSL_STUB_SIZE ((DWORD)sizeof(SSL_STUB))                // Amount of space needed by a single SSL stub
Description

Amount of space needed by a single SSL stub

Stack API > SSL > Internal Members > SSL_STUB_SIZE Macro


SSL_STUB_SPACE Macro

Contents | Index | Home
Previous | Up | Next
SSL_STUB_SPACE Macro
C
#define SSL_STUB_SPACE (SSL_STUB_SIZE*MAX_SSL_CONNECTIONS)        // Amount of space needed by all SSL stubs
Description

Amount of space needed by all SSL stubs

Stack API > SSL > Internal Members > SSL_STUB_SPACE Macro


SSL_VERSION Macro

Contents | Index | Home
Previous | Up | Next
SSL_VERSION Macro
C
#define SSL_VERSION (0x0300u)    // SSL version number
Description

SSL version number

Stack API > SSL > Internal Members > SSL_VERSION Macro


SSL_VERSION_HI Macro

Contents | Index | Home
Previous | Up | Next
SSL_VERSION_HI Macro
C
#define SSL_VERSION_HI (0x03u)        // SSL version number (high byte)
Description

SSL version number (high byte)

Stack API > SSL > Internal Members > SSL_VERSION_HI Macro


SSL_VERSION_LO Macro

Contents | Index | Home
Previous | Up | Next
SSL_VERSION_LO Macro
C
#define SSL_VERSION_LO (0x00u)        // SSL version number (low byte)
Description

SSL version number (low byte)

Stack API > SSL > Internal Members > SSL_VERSION_LO Macro


SSLBufferAlloc Function

Contents | Index | Home
Previous | Up | Next
SSLBufferAlloc Function
C
static void SSLBufferAlloc(
    BYTE * id
);
Description

Allocates a buffer for use.

Preconditions

None

Parameters
Parameters | Description
id | Where to store the allocated ID
Returns

id - Allocated buffer ID, or SSL_INVALID_ID if none available

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLBufferAlloc Function


SSLBufferFree Function

Contents | Index | Home
Previous | Up | Next
SSLBufferFree Function
C
static void SSLBufferFree(
    BYTE * id
);
Description

Specified buffer is released

Preconditions

None

Parameters
Parameters | Description
id | the buffer ID to free
Outputs | id - SSL_INVALID_ID
Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLBufferFree Function


sslBufferID Variable

Contents | Index | Home
Previous | Up | Next
sslBufferID Variable
C
BYTE sslBufferID;
Description

Which buffer is loaded

Stack API > SSL > Internal Members > sslBufferID Variable


SSLBufferSync Function

Contents | Index | Home
Previous | Up | Next
SSLBufferSync Function
C
static void SSLBufferSync(
    BYTE id
);
Description

Specified buffer is loaded to RAM. Only loads if necessary, and saves any current buffer before switching.

Preconditions

None

Parameters
Parameters | Description
id | the buffer ID to sync to RAM
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLBufferSync Function


SSLFinishPartialRecord Macro

Contents | Index | Home
Previous | Up | Next
SSLFinishPartialRecord Macro
C
#define SSLFinishPartialRecord(a) TCPSSLPutRecordHeader(a, NULL, TRUE);
Description

This is macro SSLFinishPartialRecord.

Stack API > SSL > Internal Members > SSLFinishPartialRecord Macro


SSLFlushPartialRecord Macro

Contents | Index | Home
Previous | Up | Next
SSLFlushPartialRecord Macro
C
#define SSLFlushPartialRecord(a) TCPSSLPutRecordHeader(a, NULL, FALSE);
Description

This is macro SSLFlushPartialRecord.

Stack API > SSL > Internal Members > SSLFlushPartialRecord Macro


sslHash Variable

Contents | Index | Home
Previous | Up | Next
sslHash Variable
C
HASH_SUM sslHash;
Description

Hash storage

Stack API > SSL > Internal Members > sslHash Variable


SSLHashAlloc Function

Contents | Index | Home
Previous | Up | Next
SSLHashAlloc Function
C
static void SSLHashAlloc(
    BYTE * id
);
Description

Allocates a hash for use.

Preconditions

None

Parameters
Parameters | Description
id | Where to store the allocated ID
Outputs | id - Allocated hash ID, or SSL_INVALID_ID if none available
Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLHashAlloc Function


SSLHashFree Function

Contents | Index | Home
Previous | Up | Next
SSLHashFree Function
C
static void SSLHashFree(
    BYTE * id
);
Description

Specified hash is released

Preconditions

None

Parameters
Parameters | Description
id | the hash ID to free
Outputs | id - SSL_INVALID_ID
Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLHashFree Function


sslHashID Variable

Contents | Index | Home
Previous | Up | Next
sslHashID Variable
C
BYTE sslHashID;
Description

Which hash is loaded

Stack API > SSL > Internal Members > sslHashID Variable


SSLHashSync Function

Contents | Index | Home
Previous | Up | Next
SSLHashSync Function
C
static void SSLHashSync(
    BYTE id
);
Description

Specified hash is loaded to RAM. Only loads if necessary, and saves any current hash before switching.

Preconditions

None

Parameters
Parameters | Description
id | the hash ID to sync to RAM
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLHashSync Function


sslKeys Variable

Contents | Index | Home
Previous | Up | Next
sslKeys Variable
C
SSL_KEYS sslKeys;
Description

The current SSL session

Stack API > SSL > Internal Members > sslKeys Variable


sslKeysID Variable

Contents | Index | Home
Previous | Up | Next
sslKeysID Variable
C
BYTE sslKeysID;
Description

Which SSL_KEYS are loaded

Stack API > SSL > Internal Members > sslKeysID Variable


SSLKeysSync Function

Contents | Index | Home
Previous | Up | Next
SSLKeysSync Function
C
static void SSLKeysSync(
    BYTE id
);
Description

Specified key set is loaded to RAM. Only loads if necessary, and saves any current key set before switching.

Preconditions

None

Parameters
Parameters | Description
id | the key set ID to sync to RAM
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLKeysSync Function


SSLMACAdd Function

Contents | Index | Home
Previous | Up | Next
SSLMACAdd Function
C
void SSLMACAdd(
    BYTE* data,
    WORD len
);
Description

This is function SSLMACAdd.

Stack API > SSL > Internal Members > SSLMACAdd Function


SSLMACBegin Function

Contents | Index | Home
Previous | Up | Next
SSLMACBegin Function
C
void SSLMACBegin(
    BYTE* MACSecret,
    DWORD seq,
    BYTE protocol,
    WORD len
);
Description

This is function SSLMACBegin.

Stack API > SSL > Internal Members > SSLMACBegin Function


SSLMACCalc Function

Contents | Index | Home
Previous | Up | Next
SSLMACCalc Function
C
void SSLMACCalc(
    BYTE* MACSecret,
    BYTE* result
);
Description

This is function SSLMACCalc.

Stack API > SSL > Internal Members > SSLMACCalc Function


SSLRSAOperation Function

Contents | Index | Home
Previous | Up | Next
SSLRSAOperation Function
C
static RSA_STATUS SSLRSAOperation();
Description

Pauses connection processing until RSA calculation is complete.

Preconditions

The RSA Module has been secured, an RSA operation is pending, sslStub.wRxHsBytesRem is the value of sslStub.wRxBytesRem after completion, and sslStub.wRxBytesRem is the value of sslStub.rxProtocol after completion. Also requires sslStub to be synchronized.

Returns

None

Side Effects

None

Remarks

This function exists outside of the handshaking functions so that the system does not incur the expense of resuming and suspending handshake hashes.

Stack API > SSL > Internal Members > SSLRSAOperation Function


sslRSAStubID Variable

Contents | Index | Home
Previous | Up | Next
sslRSAStubID Variable
C
BYTE sslRSAStubID;
Description

Which stub is using RSA, if any

Stack API > SSL > Internal Members > sslRSAStubID Variable


SSLRxAlert Function

Contents | Index | Home
Previous | Up | Next
SSLRxAlert Function
C
static void SSLRxAlert(
    TCP_SOCKET hTCP
);
Description

Receives an alert message and decides what to do

Preconditions

sslStub is synchronized

Parameters
Parameters | Description
hTCP | the TCP Socket to read from
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLRxAlert Function


SSLRxAntiqueClientHello Function

Contents | Index | Home
Previous | Up | Next
SSLRxAntiqueClientHello Function
C
static void SSLRxAntiqueClientHello(
    TCP_SOCKET hTCP
);
Description

Receives the SSLv2 ClientHello message, initiating a new SSL session with a client

Preconditions

Handshake hasher is started, and SSL has a stub assigned.

Parameters
Parameters | Description
hTCP | the TCP Socket to send the message to
Returns

None

Side Effects

None

Remarks

This is the only SSLv2 message we support, and is provided for browsers seeking backwards compatibility. Connections must be upgraded to SSLv3.0 immediately following, otherwise the connection will fail.

Stack API > SSL > Internal Members > SSLRxAntiqueClientHello Function


SSLRxCCS Function

Contents | Index | Home
Previous | Up | Next
SSLRxCCS Function
C
static void SSLRxCCS(
    TCP_SOCKET hTCP
);
Description

Receives a ChangeCipherSpec from the remote server

Preconditions

sslStub is synchronized.

Parameters
Parameters | Description
hTCP | the TCP Socket to read from
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLRxCCS Function


SSLRxClientHello Function

Contents | Index | Home
Previous | Up | Next
SSLRxClientHello Function
C
static void SSLRxClientHello(
    TCP_SOCKET hTCP
);
Description

Receives the ClientHello message, initiating a new SSL session with a client

Preconditions

Handshake hasher is started, and SSL has a stub assigned.

Parameters
Parameters | Description
hTCP | the TCP Socket to send the message to
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLRxClientHello Function


SSLRxClientKeyExchange Function

Contents | Index | Home
Previous | Up | Next
SSLRxClientKeyExchange Function
C
static void SSLRxClientKeyExchange(
    TCP_SOCKET hTCP
);
Description

Receives the ClientKeyExchange message and begins the decryption process.

Preconditions

sslStub is synchronized and HSStart() has been called.

Parameters
Parameters | Description
hTCP | the TCP Socket to read from
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLRxClientKeyExchange Function


SSLRxFinished Function

Contents | Index | Home
Previous | Up | Next
SSLRxFinished Function
C
static void SSLRxFinished(
    TCP_SOCKET hTCP
);
Description

Receives the Finished message from remote node

Preconditions

sslStub is synchronized and HSStart() has been called.

Parameters
Parameters | Description
hTCP | the TCP Socket to read from
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLRxFinished Function


SSLRxHandshake Function

Contents | Index | Home
Previous | Up | Next
SSLRxHandshake Function
C
void SSLRxHandshake(
    TCP_SOCKET hTCP
);
Description

This function receives handshake messages, reads the handshake header, and passes the data off to the appropriate handshake parser.

Preconditions

The specified SSL stub is initialized and the TCP socket is connected. Also requires that rxBytesRem has been populated and the current SSL stub has been synced into memory.

Parameters
Parameters | Description
hTCP | The TCP socket to read a handshake message from
Returns

None

Stack API > SSL > Internal Members > SSLRxHandshake Function


SSLRxRecord Function

Contents | Index | Home
Previous | Up | Next
SSLRxRecord Function
C
WORD SSLRxRecord(
    TCP_SOCKET hTCP,
    BYTE sslStubID
);
Description

Reads at most one SSL Record header from the TCP stream and determines what to do with the rest of the data. If not all of the data is available for the record, then the function returns and future call(s) to SSLRxRecord() will process the remaining data until the end of the record is reached. If this call process data from a past record, the next record will not be started until the next call.

Preconditions

The specified SSL stub is initialized and the TCP socket is connected.

Parameters
Parameters | Description
hTCP | The TCP socket from which to read
id | The active SSL stub ID
Returns

WORD indicating the number of data bytes there were decrypted but left in the stream.

Remarks

SSL record headers, MAC footers, and symetric cipher block padding (if any) will be extracted from the TCP stream by this function. Data will be decrypted but left in the stream.

Stack API > SSL > Internal Members > SSLRxRecord Function


SSLRxServerCertificate Function

Contents | Index | Home
Previous | Up | Next
SSLRxServerCertificate Function
C
static void SSLRxServerCertificate(
    TCP_SOCKET hTCP
);
Description

Receives ServerCertificate from the remote server, locates the public key information, and executes RSA operation.

Preconditions

sslStub is synchronized and HSStart() has been called.

Parameters
Parameters | Description
hTCP | the TCP Socket to read from
Returns

None

Side Effects

None

Remarks

This shortcuts full parsing of the certificate by just finding the Public Key Algorithm identifier for RSA. From there, the following ASN.1 struct is the public key. That struct consists of the value for N, followed by the value for E.

Stack API > SSL > Internal Members > SSLRxServerCertificate Function


SSLRxServerHello Function

Contents | Index | Home
Previous | Up | Next
SSLRxServerHello Function
C
static void SSLRxServerHello(
    TCP_SOCKET hTCP
);
Description

Receives the ServerHello from the remote server

Preconditions

sslStub is synchronized and HSStart() has been called.

Parameters
Parameters | Description
hTCP | the TCP Socket to read from
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLRxServerHello Function


sslSession Variable

Contents | Index | Home
Previous | Up | Next
sslSession Variable
C
SSL_SESSION sslSession;
Description

Current session data

Stack API > SSL > Internal Members > sslSession Variable


sslSessionID Variable

Contents | Index | Home
Previous | Up | Next
sslSessionID Variable
C
BYTE sslSessionID;
Description

Which session is loaded

Stack API > SSL > Internal Members > sslSessionID Variable


SSLSessionMatchID Function

Contents | Index | Home
Previous | Up | Next
SSLSessionMatchID Function
C
static BYTE SSLSessionMatchID(
    BYTE* SessionID
);
Description

Locates a cached SSL session for reuse. Syncs found session into RAM.

Preconditions

None

Parameters
Parameters | Description
SessionID | the session identifier to match
Returns

The matched session ID, or SSL_INVALID_ID if not found

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLSessionMatchID Function


SSLSessionMatchIP Function

Contents | Index | Home
Previous | Up | Next
SSLSessionMatchIP Function
C
static BYTE SSLSessionMatchIP(
    IP_ADDR ip
);
Description

Locates a cached SSL session for reuse

Preconditions

None

Parameters
Parameters | Description
ip | the host session to match
Returns

The matched session ID, or SSL_INVALID_ID if not found

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLSessionMatchIP Function


SSLSessionNew Function

Contents | Index | Home
Previous | Up | Next
SSLSessionNew Function
C
static BYTE SSLSessionNew();
Description

Finds space for a new SSL session

Preconditions

None

Returns

Allocated Session ID, or SSL_INVALID_ID if none available

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLSessionNew Function


sslSessionStubs Variable

Contents | Index | Home
Previous | Up | Next
sslSessionStubs Variable
C
SSL_SESSION_STUB sslSessionStubs[MAX_SSL_SESSIONS];
Description

8 byte session stubs

Stack API > SSL > Internal Members > sslSessionStubs Variable


SSLSessionSync Function

Contents | Index | Home
Previous | Up | Next
SSLSessionSync Function
C
static void SSLSessionSync(
    BYTE id
);
Description

Specified session is loaded to RAM. Only loads if necessary, and saves any current session before switching if it has been updated.

Preconditions

None

Parameters
Parameters | Description
id | the session ID to sync to RAM
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLSessionSync Function


SSLSessionUpdated Macro

Contents | Index | Home
Previous | Up | Next
SSLSessionUpdated Macro
C
#define SSLSessionUpdated sslSessionUpdated = TRUE;
Description

This is macro SSLSessionUpdated.

Stack API > SSL > Internal Members > SSLSessionUpdated Macro


sslSessionUpdated Variable

Contents | Index | Home
Previous | Up | Next
sslSessionUpdated Variable
C
BOOL sslSessionUpdated;
Description

Whether or not it has been updated

Stack API > SSL > Internal Members > sslSessionUpdated Variable


SSLStartPartialRecord Function

Contents | Index | Home
Previous | Up | Next
SSLStartPartialRecord Function
C
void SSLStartPartialRecord(
    TCP_SOCKET hTCP,
    BYTE sslStubID,
    BYTE txProtocol,
    WORD wLen
);
Description

This function allows messages longer than the TCP buffer to be sent, which is frequently the case for the Certificate handshake message. The final message length is required to be known in order to transmit the header. Once called, SSLFlushPartialRecord and SSLFinishPartialRecord must be called to write remaining data, finalize, and prepare for a new record.

Preconditions

The specified SSL stub is initialized and the TCP socket is connected.

Parameters
Parameters | Description
hTCP | The TCP socket with data waiting to be transmitted
id | The active SSL stub ID
txPortocol | The SSL protocol number to attach to this record
wLen | The length of all the data to be sent
Returns

None

Remarks

Partial messages do not support the current cipher spec, so this can only be used during the handshake procedure.

Stack API > SSL > Internal Members > SSLStartPartialRecord Function


sslStub Variable

Contents | Index | Home
Previous | Up | Next
sslStub Variable
C
SSL_STUB sslStub;
Description

The current SSL stub

Stack API > SSL > Internal Members > sslStub Variable


SSLStubAlloc Function

Contents | Index | Home
Previous | Up | Next
SSLStubAlloc Function
C
static BOOL SSLStubAlloc();
Description

Allocates a stub for use.

Preconditions

None

Parameters
Parameters | Description
Outputs | None
Returns

TRUE if stub was allocated, FALSE otherwise

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLStubAlloc Function


SSLStubFree Function

Contents | Index | Home
Previous | Up | Next
SSLStubFree Function
C
static void SSLStubFree(
    BYTE id
);
Description

Specified stub is released

Preconditions

None

Parameters
Parameters | Description
id | the stub ID to free
Outputs | None
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLStubFree Function


sslStubID Variable

Contents | Index | Home
Previous | Up | Next
sslStubID Variable
C
BYTE sslStubID;
Description

Which SSL_STUB is loaded

Stack API > SSL > Internal Members > sslStubID Variable


SSLStubSync Function

Contents | Index | Home
Previous | Up | Next
SSLStubSync Function
C
static void SSLStubSync(
    BYTE id
);
Description

Specified stub is loaded to RAM. Only loads if necessary, and saves any current stub before switching.

Preconditions

None

Parameters
Parameters | Description
id | the stub ID to sync to RAM
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLStubSync Function


SSLTerminate Function

Contents | Index | Home
Previous | Up | Next
SSLTerminate Function
C
void SSLTerminate(
    BYTE sslStubId
);
Description

Terminates an SSL connection and releases allocated resources.

Preconditions

None

Parameters
Parameters | Description
id | the SSL stub ID to terminate
Returns

None

Stack API > SSL > Internal Members > SSLTerminate Function


SSLTxCCSFin Function

Contents | Index | Home
Previous | Up | Next
SSLTxCCSFin Function
C
static void SSLTxCCSFin(
    TCP_SOCKET hTCP
);
Description

Generates the session keys from the master secret, then allocates and generates the encryption context. Once processing is complete, transmits the Change Cipher Spec message and the Finished handshake message to the server.

Preconditions

sslStub is synchronized, and the current session has a valid pre-master secret to use.

Parameters
Parameters | Description
hTCP | the TCP Socket to write the message to
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLTxCCSFin Function


SSLTxClientHello Function

Contents | Index | Home
Previous | Up | Next
SSLTxClientHello Function
C
static void SSLTxClientHello(
    TCP_SOCKET hTCP
);
Description

Transmits the ClientHello message to initiate a new SSL session with the server.

Preconditions

Enough space is available in hTCP to write the entire message.

Parameters
Parameters | Description
hTCP | the TCP Socket to send the message to
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLTxClientHello Function


SSLTxClientKeyExchange Function

Contents | Index | Home
Previous | Up | Next
SSLTxClientKeyExchange Function
C
static void SSLTxClientKeyExchange(
    TCP_SOCKET hTCP
);
Description

Transmits the encrypted pre-master secret to the server and requests the Change Cipher Spec. Also generates the Master Secret from the pre-master secret that was used.

Preconditions

sslStub is synchronized, sslStub.dwTemp.v[1] contains the length of the public key, and the RxBuffer contains the encrypted pre-master secret at address 0x80.

Parameters
Parameters | Description
hTCP | the TCP Socket to write the message to
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLTxClientKeyExchange Function


SSLTxMessage Function

Contents | Index | Home
Previous | Up | Next
SSLTxMessage Function
C
void SSLTxMessage(
    TCP_SOCKET hTCP,
    BYTE sslStubID,
    BYTE msg
);
Description

This function transmits a specific SSL message for handshakes and alert messages. Supported messages are listed in SSL_MESSAGES.

Preconditions

The specified SSL stub is initialized and the TCP socket is connected.

Parameters
Parameters | Description
hTCP | The TCP socket with data waiting to be transmitted
id | The active SSL stub ID
msg | One of the SSL_MESSAGES types to send
Returns

None

Stack API > SSL > Internal Members > SSLTxMessage Function


SSLTxRecord Function

Contents | Index | Home
Previous | Up | Next
SSLTxRecord Function
C
void SSLTxRecord(
    TCP_SOCKET hTCP,
    BYTE sslStubID,
    BYTE txProtocol
);
Description

Transmits all pending data in the TCP TX buffer as an SSL record using the specified protocol. This function transparently encrypts and MACs the data if there is an active cipher spec.

Preconditions

The specified SSL stub is initialized and the TCP socket is connected.

Parameters
Parameters | Description
hTCP | The TCP socket with data waiting to be transmitted
id | The active SSL stub ID
txPortocol | The SSL protocol number to attach to this record
Returns

None

Stack API > SSL > Internal Members > SSLTxRecord Function


SSLTxServerCertificate Function

Contents | Index | Home
Previous | Up | Next
SSLTxServerCertificate Function
C
static void SSLTxServerCertificate(
    TCP_SOCKET hTCP
);
Description

Transmits the Certificate message with the server's specified public key certificate.

Preconditions

None

Parameters
Parameters | Description
hTCP | the TCP Socket to send the message to
Returns

None

Side Effects

None

Remarks

Certificate is defined in CustomSSLCert.c. This function requires special handling for partial records because the certificate will likely be larger than the TCP buffer, and SSL handshake messages are constrained to fit in a single SSL handshake record

Stack API > SSL > Internal Members > SSLTxServerCertificate Function


SSLTxServerHello Function

Contents | Index | Home
Previous | Up | Next
SSLTxServerHello Function
C
static void SSLTxServerHello(
    TCP_SOCKET hTCP
);
Description

Transmits the ServerHello message.

Preconditions

None

Parameters
Parameters | Description
hTCP | the TCP Socket to send the message to
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLTxServerHello Function


SSLTxServerHelloDone Function

Contents | Index | Home
Previous | Up | Next
SSLTxServerHelloDone Function
C
static void SSLTxServerHelloDone(
    TCP_SOCKET hTCP
);
Description

Transmits the ServerHelloDone message.

Preconditions

None

Parameters
Parameters | Description
hTCP | the TCP Socket to send the message to
Returns

None

Side Effects

None

Remarks

None

Stack API > SSL > Internal Members > SSLTxServerHelloDone Function


TCP

Contents | Index | Home
Previous | Up | Next
TCP
Variables

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.

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.

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 TCPIsConnected will be sufficient, but TCPWasReset may also be used for listening sockets that may turn over quickly.

To write data, call TCPIsPutReady to check how much space is available. Then, call any of the TCPPut family of functions to write data as space is available. Once complete, call TCPFlush 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 (usually 40ms).

To read data, call TCPIsGetReady to determine how many bytes are ready to be retrieved. Then use the TCPGet family of functions to read data from the socket, and/or the TCPFind 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 TCPDisconnect, then return to the main stack loop and wait for the 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.

Topics
Name | Description
TCP Public Members | Functions and variables accessible by the stack application
TCP Stack Members | Functions and variables intended to be accessed only by the stack
TCP Internal Members | Functions and variables internal to the TCP module
Variables | The following table lists variables in this documentation.
Variables
Name | Description
NextPort | Tracking variable for next local client port number
Stack API > TCP


TCP Public Members

Contents | Index | Home
Previous | Up | Next
TCP Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
TCPAdjustFIFOSize | Adjusts the relative sizes of the RX and TX buffers.
TCPClose | Disconnects an open socket and destroys the socket handle, including server mode socket handles.
TCPDiscard | Discards any pending data in the TCP RX FIFO.
TCPDisconnect | Disconnects an open socket.
TCPFindArrayEx | Searches for a string in the TCP RX buffer.
TCPFindEx | Searches for a byte in the TCP RX buffer.
TCPFindROMArrayEx | Searches for a ROM string in the TCP RX buffer.
TCPFlush | Immediately transmits all pending TX data.
TCPGet | Retrieves a single byte to a TCP socket.
TCPGetArray | Reads an array of data bytes from a TCP socket's receive FIFO. The data is removed from the FIFO in the process.
TCPGetRemoteInfo | Obtains information about a currently open socket.
TCPGetRxFIFOFree | Determines how many bytes are free in the RX FIFO.
TCPGetTxFIFOFull | Determines how many bytes are pending in the TCP TX FIFO.
TCPIsConnected | Determines if a socket has an established connection.
TCPIsGetReady | Determines how many bytes can be read from the TCP RX buffer.
TCPIsPutReady | Determines how much free space is available in the TCP TX buffer.
TCPOpen | Opens a TCP socket for listening or as a client.
TCPPeek | Peaks at one byte in the TCP RX FIFO without removing it from the buffer.
TCPPeekArray | Reads a specified number of data bytes from the TCP RX FIFO without removing them from the buffer.
TCPPut | Writes a single byte to a TCP socket.
TCPPutArray | Writes an array from RAM to a TCP socket.
TCPPutROMArray | Writes an array from ROM to a TCP socket.
TCPPutROMString | Writes a null-terminated string from ROM to a TCP socket. The null-terminator is not copied to the socket.
TCPPutString | Writes a null-terminated string from RAM to a TCP socket. The null-terminator is not copied to the socket.
TCPRAMCopy | Copies data to/from various memory mediums.
TCPRAMCopyROM | Copies data to/from various memory mediums.
TCPWasReset | Self-clearing semaphore inidicating socket reset.
Macros
Name | Description
INVALID_SOCKET | The socket is invalid or could not be opened
UNKNOWN_SOCKET | The socket is not known
TCP_ADJUST_GIVE_REST_TO_RX | Resize flag: extra bytes go to RX
TCP_ADJUST_GIVE_REST_TO_TX | Resize flag: extra bytes go to TX
TCP_ADJUST_PRESERVE_RX | Resize flag: attempt to preserve RX buffer
TCP_ADJUST_PRESERVE_TX | Resize flag: attempt to preserve TX buffer
TCP_OPEN_IP_ADDRESS | Emit an undeclared identifier diagnostic if code tries to use TCP_OPEN_IP_ADDRESS while STACK_CLIENT_MODE feature is not enabled.
TCP_OPEN_NODE_INFO | Emit an undeclared identifier diagnostic if code tries to use TCP_OPEN_NODE_INFO while STACK_CLIENT_MODE feature is not enabled.
TCP_OPEN_RAM_HOST | Emit an undeclared identifier diagnostic if code tries to use TCP_OPEN_RAM_HOST while STACK_CLIENT_MODE feature is not enabled.
TCP_OPEN_ROM_HOST | Emit an undeclared identifier diagnostic if code tries to use TCP_OPEN_ROM_HOST while STACK_CLIENT_MODE feature is not enabled.
TCP_OPEN_SERVER | Create a server socket and ignore dwRemoteHost.
TCPConnect | Alias to TCPOpen as a client.
TCPFind | Alias to TCPFindEx with no length parameter.
TCPFindArray | Alias to TCPFindArrayEx with no length parameter.
TCPFindROMArray | Alias to TCPFindROMArrayEx with no length parameter.
TCPGetRxFIFOFull | Alias to TCPIsGetReady provided for API completeness
TCPGetTxFIFOFree | Alias to TCPIsPutReady provided for API completeness
TCPListen | Alias to TCPOpen as a server.
Module

TCP

Stack API > TCP > Public Members


INVALID_SOCKET Macro

Contents | Index | Home
Previous | Up | Next
INVALID_SOCKET Macro
C
#define INVALID_SOCKET (0xFE)    // The socket is invalid or could not be opened
Description

The socket is invalid or could not be opened

Stack API > TCP > Public Members > INVALID_SOCKET Macro


UNKNOWN_SOCKET Macro

Contents | Index | Home
Previous | Up | Next
UNKNOWN_SOCKET Macro
C
#define UNKNOWN_SOCKET (0xFF)    // The socket is not known
Description

The socket is not known

Stack API > TCP > Public Members > UNKNOWN_SOCKET Macro


TCP_ADJUST_GIVE_REST_TO_RX Macro

Contents | Index | Home
Previous | Up | Next
TCP_ADJUST_GIVE_REST_TO_RX Macro
C
#define TCP_ADJUST_GIVE_REST_TO_RX 0x01u    // Resize flag: extra bytes go to RX
Description

Resize flag: extra bytes go to RX

Stack API > TCP > Public Members > TCP_ADJUST_GIVE_REST_TO_RX Macro


TCP_ADJUST_GIVE_REST_TO_TX Macro

Contents | Index | Home
Previous | Up | Next
TCP_ADJUST_GIVE_REST_TO_TX Macro
C
#define TCP_ADJUST_GIVE_REST_TO_TX 0x02u    // Resize flag: extra bytes go to TX
Description

Resize flag: extra bytes go to TX

Stack API > TCP > Public Members > TCP_ADJUST_GIVE_REST_TO_TX Macro


TCP_ADJUST_PRESERVE_RX Macro

Contents | Index | Home
Previous | Up | Next
TCP_ADJUST_PRESERVE_RX Macro
C
#define TCP_ADJUST_PRESERVE_RX 0x04u    // Resize flag: attempt to preserve RX buffer
Description

Resize flag: attempt to preserve RX buffer

Stack API > TCP > Public Members > TCP_ADJUST_PRESERVE_RX Macro


TCP_ADJUST_PRESERVE_TX Macro

Contents | Index | Home
Previous | Up | Next
TCP_ADJUST_PRESERVE_TX Macro
C
#define TCP_ADJUST_PRESERVE_TX 0x08u    // Resize flag: attempt to preserve TX buffer
Description

Resize flag: attempt to preserve TX buffer

Stack API > TCP > Public Members > TCP_ADJUST_PRESERVE_TX Macro


TCP_OPEN_IP_ADDRESS Macro

Contents | Index | Home
Previous | Up | Next
TCP_OPEN_IP_ADDRESS Macro
C
#define TCP_OPEN_IP_ADDRESS You_need_to_enable_STACK_CLIENT_MODE_to_use_TCP_OPEN_IP_ADDRESS
Description

Emit an undeclared identifier diagnostic if code tries to use TCP_OPEN_IP_ADDRESS while STACK_CLIENT_MODE feature is not enabled.

Stack API > TCP > Public Members > TCP_OPEN_IP_ADDRESS Macro


TCP_OPEN_NODE_INFO Macro

Contents | Index | Home
Previous | Up | Next
TCP_OPEN_NODE_INFO Macro
C
#define TCP_OPEN_NODE_INFO You_need_to_enable_STACK_CLIENT_MODE_to_use_TCP_OPEN_NODE_INFO
Description

Emit an undeclared identifier diagnostic if code tries to use TCP_OPEN_NODE_INFO while STACK_CLIENT_MODE feature is not enabled.

Stack API > TCP > Public Members > TCP_OPEN_NODE_INFO Macro


TCP_OPEN_RAM_HOST Macro

Contents | Index | Home
Previous | Up | Next
TCP_OPEN_RAM_HOST Macro
C
#define TCP_OPEN_RAM_HOST You_need_to_enable_STACK_CLIENT_MODE_to_use_TCP_OPEN_RAM_HOST
Description

Emit an undeclared identifier diagnostic if code tries to use TCP_OPEN_RAM_HOST while STACK_CLIENT_MODE feature is not enabled.

Stack API > TCP > Public Members > TCP_OPEN_RAM_HOST Macro


TCP_OPEN_ROM_HOST Macro

Contents | Index | Home
Previous | Up | Next
TCP_OPEN_ROM_HOST Macro
C
#define TCP_OPEN_ROM_HOST You_need_to_enable_STACK_CLIENT_MODE_to_use_TCP_OPEN_ROM_HOST
Description

Emit an undeclared identifier diagnostic if code tries to use TCP_OPEN_ROM_HOST while STACK_CLIENT_MODE feature is not enabled.

Stack API > TCP > Public Members > TCP_OPEN_ROM_HOST Macro


TCP_OPEN_SERVER Macro

Contents | Index | Home
Previous | Up | Next
TCP_OPEN_SERVER Macro
C
#define TCP_OPEN_SERVER 0u
Description

Create a server socket and ignore dwRemoteHost.

Stack API > TCP > Public Members > TCP_OPEN_SERVER Macro


TCPAdjustFIFOSize Function

Contents | Index | Home
Previous | Up | Next
TCPAdjustFIFOSize Function
C
BOOL TCPAdjustFIFOSize(
    TCP_SOCKET hTCP,
    WORD wMinRXSize,
    WORD wMinTXSize,
    BYTE vFlags
);
Description

This function can be used to adjust the relative sizes of the RX and TX FIFO depending on the immediate needs of an application. Since a larger FIFO can allow more data to be sent in a given packet, adjusting the relative sizes 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 substantially. Once the FIFO is adjusted, a window update is sent.

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 equally.

Received data can be preserved as long as the buffer is expanding and has not wrapped.

Preconditions

TCP is initialized.

Parameters
Parameters | Description
hTCP | The socket to be adjusted
wMinRXSize | Minimum number of byte for the RX FIFO
wMinTXSize | Minimum number of bytes for the RX FIFO
vFlags | Any combination of TCP_ADJUST_GIVE_REST_TO_RX, TCP_ADJUST_GIVE_REST_TO_TX, TCP_ADJUST_PRESERVE_RX. TCP_ADJUST_PRESERVE_TX is not currently supported.
Return Values
Return Values | Description
TRUE | The FIFOs were adjusted successfully
FALSE | Minimum RX, Minimum TX, or flags couldn't be accommodated and therefore the socket was left unchanged.
Side Effects

Any unacknowledged or untransmitted data in the TX FIFO is always deleted.

Remarks

At least one byte must always be allocated to the RX buffer so that a FIN can be received. The function automatically corrects for this.

Stack API > TCP > Public Members > TCPAdjustFIFOSize Function


TCPConnect Macro

Contents | Index | Home
Previous | Up | Next
TCPConnect Macro
C
#define TCPConnect(remote,port) TCPOpen((DWORD)remote, TCP_OPEN_NODE_INFO, port, TCP_PURPOSE_DEFAULT)
Description

This function is an alias to TCPOpen for client sockets. It is provided for backwards compatibility with older versions of the stack. New applications should use the TCPOpen API instead.

Stack API > TCP > Public Members > TCPConnect Macro


TCPClose Function

Contents | Index | Home
Previous | Up | Next
TCPClose Function
C
void TCPClose(
    TCP_SOCKET hTCP
);
Description

Disconnects an open socket and destroys the socket handle, including server mode socket handles. This function performs identically to the TCPDisconnect() function, except that both client and server mode socket handles are relinquished to the TCP/IP stack upon return.

Preconditions

None

Parameters
Parameters | Description
hTCP | Handle to the socket to disconnect and close.
Returns

None

Stack API > TCP > Public Members > TCPClose Function


TCPDiscard Function

Contents | Index | Home
Previous | Up | Next
TCPDiscard Function
C
void TCPDiscard(
    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

None

Stack API > TCP > Public Members > TCPDiscard Function


TCPDisconnect Function

Contents | Index | Home
Previous | Up | Next
TCPDisconnect Function
C
void TCPDisconnect(
    TCP_SOCKET hTCP
);
Description

This function closes a connection to a remote node by sending a FIN (if currently connected).

The function can be called a second time to force a socket closed by sending a RST packet. This is useful when the application knows that the remote node will not send an ACK (if it has crashed or lost its link), or when the application needs to reuse the socket immediately regardless of whether or not the remote node would like to transmit more data before closing.

For client mode sockets, upon return, the hTCP handle is relinquished to the TCP/IP stack and must no longer be used by the application (except for an immediate subsequent call to TCPDisconnect() to force a RST transmission, if needed).

For server mode sockets, upon return, the hTCP handle is NOT relinquished to the TCP/IP stack. After closing, the socket returns to the listening state allowing future connection requests to be serviced. This leaves the hTCP handle in a valid state and must be retained for future operations on the socket. If you want to close the server and relinquish the socket back to the TCP/IP stack, call the TCPClose() API instead of TCPDisconnect().

Preconditions

None

Parameters
Parameters | Description
hTCP | Handle of the socket to disconnect.
Returns

None

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.

Stack API > TCP > Public Members > TCPDisconnect Function


TCPFind Macro

Contents | Index | Home
Previous | Up | Next
TCPFind Macro
C
#define TCPFind(a,b,c,d) TCPFindEx(a,b,c,0,d)
Description

This function is an alias to TCPFindEx with no length parameter. It is provided for backwards compatibility with an older API.

Stack API > TCP > Public Members > TCPFind Macro


TCPFindArray Macro

Contents | Index | Home
Previous | Up | Next
TCPFindArray Macro
C
#define TCPFindArray(a,b,c,d,e) TCPFindArrayEx(a,b,c,d,0,e)
Description

This function is an alias to TCPFindArrayEx with no length parameter. It is provided for backwards compatibility with an older API.

Stack API > TCP > Public Members > TCPFindArray Macro


TCPFindArrayEx Function

Contents | Index | Home
Previous | Up | Next
TCPFindArrayEx Function
C
WORD TCPFindArrayEx(
    TCP_SOCKET hTCP,
    BYTE* cFindArray,
    WORD wLen,
    WORD wStart,
    WORD 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
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 HTTP2 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.

Stack API > TCP > Public Members > TCPFindArrayEx Function


TCPFindEx Function

Contents | Index | Home
Previous | Up | Next
TCPFindEx Function
C
WORD TCPFindEx(
    TCP_SOCKET hTCP,
    BYTE cFind,
    WORD wStart,
    WORD 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 HTTP2 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.

Stack API > TCP > Public Members > TCPFindEx Function


TCPFindROMArray Macro

Contents | Index | Home
Previous | Up | Next
TCPFindROMArray Macro
C
#define TCPFindROMArray(a,b,c,d,e) TCPFindArray(a,(BYTE*)b,c,d,e)
Description

This function is an alias to TCPFindROMArrayEx with no length parameter. It is provided for backwards compatibility with an older API.

Stack API > TCP > Public Members > TCPFindROMArray Macro


TCPFindROMArrayEx Function

Contents | Index | Home
Previous | Up | Next
TCPFindROMArrayEx Function
C
WORD TCPFindROMArrayEx(
    TCP_SOCKET hTCP,
    ROM BYTE* cFindArray,
    WORD wLen,
    WORD wStart,
    WORD 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
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 HTTP2 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.

This function is aliased to TCPFindArrayEx on non-PIC18 platforms.

Stack API > TCP > Public Members > TCPFindROMArrayEx Function


TCPFlush Function

Contents | Index | Home
Previous | Up | Next
TCPFlush Function
C
void TCPFlush(
    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.

Stack API > TCP > Public Members > TCPFlush Function


TCPGet Function

Contents | Index | Home
Previous | Up | Next
TCPGet Function
C
BOOL TCPGet(
    TCP_SOCKET hTCP,
    BYTE* byte
);
Description

Retrieves a single byte to a TCP socket.

Preconditions

TCP is initialized.

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
TRUE | A byte was read from the buffer.
FALSE | The buffer was empty, or the socket is not connected.
Stack API > TCP > Public Members > TCPGet Function


TCPGetArray Function

Contents | Index | Home
Previous | Up | Next
TCPGetArray Function
C
WORD TCPGetArray(
    TCP_SOCKET hTCP,
    BYTE* buffer,
    WORD 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.

Stack API > TCP > Public Members > TCPGetArray Function


TCPGetRemoteInfo Function

Contents | Index | Home
Previous | Up | Next
TCPGetRemoteInfo Function
C
SOCKET_INFO* TCPGetRemoteInfo(
    TCP_SOCKET hTCP
);
Description

Returns the 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

The SOCKET_INFO structure associated with this socket. This structure is allocated statically by the function and is valid only until the next time TCPGetRemoteInfo() is called.

Stack API > TCP > Public Members > TCPGetRemoteInfo Function


TCPGetRxFIFOFree Function

Contents | Index | Home
Previous | Up | Next
TCPGetRxFIFOFree Function
C
WORD TCPGetRxFIFOFree(
    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 TCPGet family functions.

Stack API > TCP > Public Members > TCPGetRxFIFOFree Function


TCPGetRxFIFOFull Macro

Contents | Index | Home
Previous | Up | Next
TCPGetRxFIFOFull Macro
C
#define TCPGetRxFIFOFull(a) TCPIsGetReady(a)
Description

Alias to TCPIsGetReady provided for API completeness

Stack API > TCP > Public Members > TCPGetRxFIFOFull Macro


TCPGetTxFIFOFree Macro

Contents | Index | Home
Previous | Up | Next
TCPGetTxFIFOFree Macro
C
#define TCPGetTxFIFOFree(a) TCPIsPutReady(a)
Description

Alias to TCPIsPutReady provided for API completeness

Stack API > TCP > Public Members > TCPGetTxFIFOFree Macro


TCPGetTxFIFOFull Function

Contents | Index | Home
Previous | Up | Next
TCPGetTxFIFOFull Function
C
WORD TCPGetTxFIFOFull(
    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.

Stack API > TCP > Public Members > TCPGetTxFIFOFull Function


TCPIsConnected Function

Contents | Index | Home
Previous | Up | Next
TCPIsConnected Function
C
BOOL TCPIsConnected(
    TCP_SOCKET hTCP
);
Description

This function determines if a socket has an established connection to a remote node. Call this function after calling TCPOpen to determine when the connection is set up and ready for use. This function was historically used to check for disconnections, but TCPWasReset is now a more appropriate solution.

Preconditions

TCP is initialized.

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.

Stack API > TCP > Public Members > TCPIsConnected Function


TCPIsGetReady Function

Contents | Index | Home
Previous | Up | Next
TCPIsGetReady Function
C
WORD TCPIsGetReady(
    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.

Stack API > TCP > Public Members > TCPIsGetReady Function


TCPIsPutReady Function

Contents | Index | Home
Previous | Up | Next
TCPIsPutReady Function
C
WORD TCPIsPutReady(
    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.

Stack API > TCP > Public Members > TCPIsPutReady Function


TCPListen Macro

Contents | Index | Home
Previous | Up | Next
TCPListen Macro
C
#define TCPListen(port) TCPOpen(0, TCP_OPEN_SERVER, port, TCP_PURPOSE_DEFAULT)
Description

This function is an alias to TCPOpen for server sockets. It is provided for backwards compatibility with older versions of the stack. New applications should use the TCPOpen API instead.

Stack API > TCP > Public Members > TCPListen Macro


TCPOpen Function

Contents | Index | Home
Previous | Up | Next
TCPOpen Function
C
TCP_SOCKET TCPOpen(
    DWORD dwRemoteHost,
    BYTE vRemoteHostType,
    WORD wPort,
    BYTE vSocketPurpose
);
Description

Provides a unified method for opening TCP sockets. This function can open both client and server sockets. For client sockets, it can accept a host name string to query in DNS, an IP address as a string, an IP address in binary form, or a previously resolved NODE_INFO structure containing the remote IP address and associated MAC address. When a host name or IP address only is provided, the TCP module will internally perform the necessary DNS and/or ARP resolution steps before reporting that the TCP socket is connected (via a call to TCPISConnected returning TRUE). Server sockets ignore this destination parameter and listen only on the indicated port.

The vSocketPurpose field allows sockets to be opened with varying buffer size parameters and memory storage mediums. This field corresponds to pre-defined sockets allocated in the TCPSocketInitializer[] array in TCPIPConfig.h. The TCPIPConfig.h file can be edited using the TCP/IP Configuration Wizard.

Sockets are statically allocated on boot, but can be claimed with this function and freed using TCPDisconnect or TCPClose (for client sockets). Server sockets can be freed using TCPClose only (calls to TCPDisconnect will return server sockets to the listening state, allowing reuse).

Preconditions

TCP is initialized.

Parameters
Parameters
Description
dwRemoteHost
For client sockets only. Provide a pointer to a null-terminated string of the remote host name (ex: "www.microchip.com" or "192.168.1.123"), a literal destination IP address (ex: 0x7B01A8C0 or an IP_ADDR data type), or a pointer to a NODE_INFO structure with the remote IP address and remote node or gateway MAC address specified. If a string is provided, note that it must be statically allocated in memory and cannot be modified or deallocated until TCPIsConnected returns TRUE.
This parameter is ignored for server sockets.
vRemoteHostType
Any one of the following flags to identify the meaning of the dwRemoteHost parameter:

  • TCP_OPEN_SERVER - Open a server socket and ignore the dwRemoteHost parameter.
  • TCP_OPEN_RAM_HOST - Open a client socket and connect it to a remote host who's name is stored as a null terminated string in a RAM array. Ex: "www.microchip.com" or "192.168.0.123" (BYTE* type)
  • TCP_OPEN_ROM_HOST - Open a client socket and connect it to a remote host who's name is stored as a null terminated string in a literal string or ROM array. Ex: "www.microchip.com" or "192.168.0.123" (ROM BYTE* type)
  • TCP_OPEN_IP_ADDRESS - Open a client socket and connect it to a remote IP address. Ex: 0x7B01A8C0 for 192.168.1.123 (DWORD type). Note that the byte ordering is big endian.
  • TCP_OPEN_NODE_INFO - Open a client socket and connect it to a remote IP and MAC addresses pair stored in a NODE_INFO structure. dwRemoteHost must be a pointer to the NODE_INFO structure. This option is provided for backwards compatibility with applications built against prior stack versions that only implemented the TCPConnect() function. It can also be used to skip DNS and ARP resolution steps if connecting to a remote node which you've already connected to and have cached addresses for.

wPort
TCP port to listen on or connect to:

  • Client sockets - the remote TCP port to which a connection should be made. The local port for client sockets will be automatically picked by the TCP module.
  • Server sockets - the local TCP port on which to listen for connections.

vSocketPurpose
Any of the TCP_PURPOSE_* constants defined in TCPIPConfig.h or the TCPIPConfig utility (see TCPSocketInitializer[] array).
Return Values
Return Values | Description
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

This function replaces the old TCPConnect and TCPListen functions.

If TCP_OPEN_RAM_HOST or TCP_OPEN_ROM_HOST are used for the destination type, the DNS client module must also be enabled (STACK_USE_DNS must be defined in TCPIPConfig.h).

Example

Copy Code
// Open a server socket
skt = TCPOpen(NULL, TCP_OPEN_SERVER, HTTP_PORT, TCP_PURPOSE_HTTP_SERVER);

// Open a client socket to www.microchip.com
// The double cast here prevents compiler warnings
skt = TCPOpen((DWORD)(PTR_BASE)"www.microchip.com",
                TCP_OPEN_ROM_HOST, 80, TCP_PURPOSE_DEFAULT);

// Reopen a client socket without repeating DNS or ARP
SOCKET_INFO cache = TCPGetSocketInfo(skt);  // Call with the old socket
skt = TCPOpen((DWORD)(PTR_BASE)&cache.remote, TCP_OPEN_NODE_INFO,
                cache.remotePort.Val, TCP_PURPOSE_DEFAULT);
Stack API > TCP > Public Members > TCPOpen Function


TCPPeek Function

Contents | Index | Home
Previous | Up | Next
TCPPeek Function
C
BYTE TCPPeek(
    TCP_SOCKET hTCP,
    WORD 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 TCPPeekArray() function to read more than one byte. It will perform better than calling TCPPeek() in a loop.

Stack API > TCP > Public Members > TCPPeek Function


TCPPeekArray Function

Contents | Index | Home
Previous | Up | Next
TCPPeekArray Function
C
WORD TCPPeekArray(
    TCP_SOCKET hTCP,
    BYTE * vBuffer,
    WORD wLen,
    WORD 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).
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

Stack API > TCP > Public Members > TCPPeekArray Function


TCPPut Function

Contents | Index | Home
Previous | Up | Next
TCPPut Function
C
BOOL TCPPut(
    TCP_SOCKET hTCP,
    BYTE byte
);
Description

Writes a single byte to a TCP socket.

Preconditions

TCP is initialized.

Parameters
Parameters | Description
hTCP | The socket to which data is to be written.
byte | The byte to write.
Return Values
Return Values | Description
TRUE | The byte was written to the transmit buffer.
FALSE | The transmit buffer was full, or the socket is not connected.
Stack API > TCP > Public Members > TCPPut Function


TCPPutArray Function

Contents | Index | Home
Previous | Up | Next
TCPPutArray Function
C
WORD TCPPutArray(
    TCP_SOCKET hTCP,
    BYTE* Data,
    WORD 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.

Stack API > TCP > Public Members > TCPPutArray Function


TCPPutROMArray Function

Contents | Index | Home
Previous | Up | Next
TCPPutROMArray Function
C
WORD TCPPutROMArray(
    TCP_SOCKET hTCP,
    ROM BYTE* Data,
    WORD Len
);
Description

Writes an array from ROM 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.

Remarks

This function is aliased to TCPPutArray on non-PIC18 platforms.

Stack API > TCP > Public Members > TCPPutROMArray Function


TCPPutROMString Function

Contents | Index | Home
Previous | Up | Next
TCPPutROMString Function
C
ROM BYTE* TCPPutROMString(
    TCP_SOCKET hTCP,
    ROM BYTE* Data
);
Description

Writes a null-terminated string from ROM to a TCP socket. The null-terminator is not copied to the socket.

Preconditions

TCP is initialized.

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 TCPPutArray. 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.

This function is aliased to TCPPutString on non-PIC18 platforms.

Stack API > TCP > Public Members > TCPPutROMString Function


TCPPutString Function

Contents | Index | Home
Previous | Up | Next
TCPPutString Function
C
BYTE* TCPPutString(
    TCP_SOCKET hTCP,
    BYTE* 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.

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 TCPPutArray. 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.

Stack API > TCP > Public Members > TCPPutString Function


TCPRAMCopy Function

Contents | Index | Home
Previous | Up | Next
TCPRAMCopy Function
C
static void TCPRAMCopy(
    PTR_BASE wDest,
    BYTE vDestType,
    PTR_BASE wSource,
    BYTE vSourceType,
    WORD wLength
);
Description

This function copies data between memory mediums (PIC RAM, SPI RAM, and Ethernet buffer RAM).

Preconditions

TCP is initialized.

Parameters
Parameters | Description
ptrDest | Address to write to
vDestType | Destination meidum (TCP_PIC_RAM, TCP_ETH_RAM, TCP_SPI_RAM)
ptrSource | Address to copy from
vSourceType | Source medium (TCP_PIC_RAM, TCP_ETH_RAM, or TCP_SPI_RAM)
wLength | Number of bytes to copy
Returns

None

Remarks

Copying to a destination region that overlaps with the source address is supported only if the destination start address is at a lower memory address (closer to 0x0000) than the source pointer. However, if they do overlap there must be at least 4 bytes of non-overlap to ensure correct results due to hardware DMA requirements.

Stack API > TCP > Public Members > TCPRAMCopy Function


TCPRAMCopyROM Function

Contents | Index | Home
Previous | Up | Next
TCPRAMCopyROM Function
C
static void TCPRAMCopyROM(
    PTR_BASE wDest,
    BYTE wDestType,
    ROM BYTE* wSource,
    WORD wLength
);
Description

This function copies data between memory mediums (PIC RAM, SPI RAM, and Ethernet buffer RAM). This function is to be used when copying from ROM.

Preconditions

TCP is initialized.

Parameters
Parameters | Description
wDest | Address to write to
wDestType | Destination meidum (TCP_PIC_RAM, TCP_ETH_RAM, TCP_SPI_RAM)
wSource | Address to copy from
wLength | Number of bytes to copy
Returns

None

Remarks

Copying to a destination region that overlaps with the source address is supported only if the destination start address is at a lower memory address (closer to 0x0000) than the source pointer.

This function is aliased to TCPRAMCopy on non-PIC18 platforms.

Stack API > TCP > Public Members > TCPRAMCopyROM Function


TCPWasReset Function

Contents | Index | Home
Previous | Up | Next
TCPWasReset Function
C
BOOL TCPWasReset(
    TCP_SOCKET hTCP
);
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 TCPDisconnect, 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 TCPInit. Applications should use this function to reset their state machines.

This function was added due to the possibility of an error when relying on TCPIsConnected returing FALSE to check for a condition requiring a state machine reset. If a socket is closed (due to a FIN ACK) and then immediately reopened (due to a the arrival of a new SYN) in the same cycle of the stack, calls to TCPIsConnected by the application will never return FALSE even though the socket has been disconnected. This can cause errors for protocols such as HTTP in which a client will immediately open a new connection upon closing of a prior one. Relying on this function instead allows applications to trap those conditions and properly reset their internal state for the new connection.

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.
Stack API > TCP > Public Members > TCPWasReset Function


TCP Stack Members

Contents | Index | Home
Previous | Up | Next
TCP Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Enumerations
Name | Description
TCP_STATE | TCP States as defined by RFC 793
Functions
Name | Description
TCPInit | Initializes the TCP module.
TCPProcess | Handles incoming TCP segments.
TCPTick | Performs periodic TCP tasks.
TCPSSLDecryptMAC | Decrypts and MACs data arriving via SSL.
TCPStartSSLClientEx | Begins an SSL client session.
Module

TCP

Structures
Name | Description
SOCKET_INFO | Information about a socket
TCB | Remainder of TCP Control Block data. The rest of the TCB is stored in Ethernet buffer RAM or elsewhere as defined by vMemoryMedium. Current size is 41 (PIC18), 42 (PIC24/dsPIC), or 48 bytes (PIC32)
TCB_STUB | TCP Control Block (TCB) stub data storage. Stubs are stored in local PIC RAM for speed. Current size is 34 bytes (PIC18), 36 bytes (PIC24/dsPIC), or 56 (PIC32)
Types
Name | Description
TCP_SOCKET | A TCP_SOCKET is stored as a single BYTE
Stack API > TCP > Stack Members


SOCKET_INFO Structure

Contents | Index | Home
Previous | Up | Next
SOCKET_INFO Structure
C
typedef struct {
  NODE_INFO remote;
  WORD_VAL remotePort;
} SOCKET_INFO;
Description

Information about a socket

Members
Members | Description
NODE_INFO remote; | NODE_INFO structure for remote node
WORD_VAL remotePort; | Port number associated with remote node
Stack API > TCP > Stack Members > SOCKET_INFO Structure


TCB Structure

Contents | Index | Home
Previous | Up | Next
TCB Structure
C
typedef struct {
  DWORD retryInterval;
  DWORD MySEQ;
  DWORD RemoteSEQ;
  PTR_BASE txUnackedTail;
  WORD_VAL remotePort;
  WORD_VAL localPort;
  WORD remoteWindow;
  WORD wFutureDataSize;
  union {
    NODE_INFO niRemoteMACIP;
    DWORD dwRemoteHost;
  } remote;
  SHORT sHoleSize;
  struct {
    unsigned char bFINSent : 1;
    unsigned char bSYNSent : 1;
    unsigned char bRemoteHostIsROM : 1;
    unsigned char bRXNoneACKed1 : 1;
    unsigned char bRXNoneACKed2 : 1;
    unsigned char filler : 3;
  } flags;
  WORD wRemoteMSS;
  WORD_VAL localSSLPort;
  BYTE retryCount;
  BYTE vSocketPurpose;
} TCB;
Description

Remainder of TCP Control Block data. The rest of the TCB is stored in Ethernet buffer RAM or elsewhere as defined by vMemoryMedium. Current size is 41 (PIC18), 42 (PIC24/dsPIC), or 48 bytes (PIC32)

Members
Members | Description
DWORD retryInterval; | How long to wait before retrying transmission
DWORD MySEQ; | Local sequence number
DWORD RemoteSEQ; | Remote sequence number
PTR_BASE txUnackedTail; | TX tail pointer for data that is not yet acked
WORD_VAL remotePort; | Remote port number
WORD_VAL localPort; | Local port number
WORD remoteWindow; | Remote window size
WORD wFutureDataSize; | How much out-of-order data has been received
NODE_INFO niRemoteMACIP; | 10 bytes for MAC and IP address
DWORD dwRemoteHost; | RAM or ROM pointer to a hostname string (ex: "www.microchip.com")
SHORT sHoleSize; | Size of the hole, or -1 for none exists. (0 indicates hole has just been filled)
unsigned char bFINSent : 1; | A FIN has been sent
unsigned char bSYNSent : 1; | A SYN has been sent
unsigned char bRemoteHostIsROM : 1; | Remote host is stored in ROM
unsigned char bRXNoneACKed1 : 1; | A duplicate ACK was likely received
unsigned char bRXNoneACKed2 : 1; | A second duplicate ACK was likely received
unsigned char filler : 3; | future use
WORD wRemoteMSS; | Maximum Segment Size option advirtised by the remote node during initial handshaking
WORD_VAL localSSLPort; | Local SSL port number (for listening sockets)
BYTE retryCount; | Counter for transmission retries
BYTE vSocketPurpose; | Purpose of socket (as defined in TCPIPConfig.h)
Stack API > TCP > Stack Members > TCB Structure


TCB_STUB Structure

Contents | Index | Home
Previous | Up | Next
TCB_STUB Structure
C
typedef struct {
  PTR_BASE bufferTxStart;
  PTR_BASE bufferRxStart;
  PTR_BASE bufferEnd;
  PTR_BASE txHead;
  PTR_BASE txTail;
  PTR_BASE rxHead;
  PTR_BASE rxTail;
  DWORD eventTime;
  WORD eventTime2;
  union {
    WORD delayedACKTime;
    WORD closeWaitTime;
  } OverlappedTimers;
  TCP_STATE smState;
  struct {
    unsigned char vUnackedKeepalives : 3;
    unsigned char bServer : 1;
    unsigned char bTimerEnabled : 1;
    unsigned char bTimer2Enabled : 1;
    unsigned char bDelayedACKTimerEnabled : 1;
    unsigned char bOneSegmentReceived : 1;
    unsigned char bHalfFullFlush : 1;
    unsigned char bTXASAP : 1;
    unsigned char bTXASAPWithoutTimerReset : 1;
    unsigned char bTXFIN : 1;
    unsigned char bSocketReset : 1;
    unsigned char bSSLHandshaking : 1;
    unsigned char filler : 2;
  } Flags;
  WORD_VAL remoteHash;
  PTR_BASE sslTxHead;
  PTR_BASE sslRxHead;
  BYTE sslStubID;
  BYTE sslReqMessage;
  BYTE vMemoryMedium;
} TCB_STUB;
Description

TCP Control Block (TCB) stub data storage. Stubs are stored in local PIC RAM for speed. Current size is 34 bytes (PIC18), 36 bytes (PIC24/dsPIC), or 56 (PIC32)

Members
Members | Description
PTR_BASE bufferTxStart; | First byte of TX buffer
PTR_BASE bufferRxStart; | First byte of RX buffer. TX buffer ends 1 byte prior
PTR_BASE bufferEnd; | Last byte of RX buffer
PTR_BASE txHead; | Head pointer for TX
PTR_BASE txTail; | Tail pointer for TX
PTR_BASE rxHead; | Head pointer for RX
PTR_BASE rxTail; | Tail pointer for RX
DWORD eventTime; | Packet retransmissions, state changes
WORD eventTime2; | Window updates, automatic transmission
WORD delayedACKTime; | Delayed Acknowledgement timer
WORD closeWaitTime; | TCP_CLOSE_WAIT timeout timer
TCP_STATE smState; | State of this socket
unsigned char vUnackedKeepalives : 3; | Count of how many keepalives have been sent with no response
unsigned char bServer : 1; | Socket should return to listening state when closed
unsigned char bTimerEnabled : 1; | Timer is enabled
unsigned char bTimer2Enabled : 1; | Second timer is enabled
unsigned char bDelayedACKTimerEnabled : 1; | DelayedACK timer is enabled
unsigned char bOneSegmentReceived : 1; | A segment has been received
unsigned char bHalfFullFlush : 1; | Flush is for being half full
unsigned char bTXASAP : 1; | Transmit as soon as possible (for Flush)
unsigned char bTXASAPWithoutTimerReset : 1; | Transmit as soon as possible (for Flush), but do not reset retransmission timers
unsigned char bTXFIN : 1; | FIN needs to be transmitted
unsigned char bSocketReset : 1; | Socket has been reset (self-clearing semaphore)
unsigned char bSSLHandshaking : 1; | Socket is in an SSL handshake
unsigned char filler : 2; | Future expansion
WORD_VAL remoteHash; | Consists of remoteIP, remotePort, localPort for connected sockets. It is a localPort number only for listening server sockets.
PTR_BASE sslTxHead; | Position of data being written in next SSL application record Also serves as cache of localSSLPort when smState = TCP_LISTENING
PTR_BASE sslRxHead; | Position of incoming data not yet handled by SSL
BYTE sslStubID; | Which sslStub is associated with this connection
BYTE sslReqMessage; | Currently requested SSL message
BYTE vMemoryMedium; | Which memory medium the TCB is actually stored
Stack API > TCP > Stack Members > TCB_STUB Structure


TCP_SOCKET Type

Contents | Index | Home
Previous | Up | Next
TCP_SOCKET Type
C
typedef BYTE TCP_SOCKET;
Description

A TCP_SOCKET is stored as a single BYTE

Stack API > TCP > Stack Members > TCP_SOCKET Type


TCP_STATE Enumeration

Contents | Index | Home
Previous | Up | Next
TCP_STATE Enumeration
C
typedef enum {
  TCP_GET_DNS_MODULE,
  TCP_DNS_RESOLVE,
  TCP_GATEWAY_SEND_ARP,
  TCP_GATEWAY_GET_ARP,
  TCP_LISTEN,
  TCP_SYN_SENT,
  TCP_SYN_RECEIVED,
  TCP_ESTABLISHED,
  TCP_FIN_WAIT_1,
  TCP_FIN_WAIT_2,
  TCP_CLOSING,
  TCP_CLOSE_WAIT,
  TCP_LAST_ACK,
  TCP_CLOSED,
  TCP_CLOSED_BUT_RESERVED
} TCP_STATE;
Description

TCP States as defined by RFC 793

Members
Members | Description
TCP_GET_DNS_MODULE | Special state for TCP client mode sockets
TCP_DNS_RESOLVE | Special state for TCP client mode sockets
TCP_GATEWAY_SEND_ARP | Special state for TCP client mode sockets
TCP_GATEWAY_GET_ARP | Special state for TCP client mode sockets
TCP_LISTEN | Socket is listening for connections
TCP_SYN_SENT | A SYN has been sent, awaiting an SYN+ACK
TCP_SYN_RECEIVED | A SYN has been received, awaiting an ACK
TCP_ESTABLISHED | Socket is connected and connection is established
TCP_FIN_WAIT_1 | FIN WAIT state 1
TCP_FIN_WAIT_2 | FIN WAIT state 2
TCP_CLOSING | Socket is closing TCP_TIME_WAIT, state is not implemented
TCP_CLOSE_WAIT | Waiting to close the socket
TCP_LAST_ACK | The final ACK has been sent
TCP_CLOSED | Socket is idle and unallocated
TCP_CLOSED_BUT_RESERVED | Special state for TCP client mode sockets. Socket is idle, but still allocated pending application closure of the handle.
Stack API > TCP > Stack Members > TCP_STATE Enumeration


TCPInit Function

Contents | Index | Home
Previous | Up | Next
TCPInit Function
C
void TCPInit();
Description

Initializes the TCP module. This function sets up the TCP buffers in memory and initializes each socket to the CLOSED state. If insufficient memory was allocated for the TCP sockets, the function will hang here to be captured by the debugger.

Preconditions

None

Returns

None

Remarks

This function is called only one during lifetime of the application.

Stack API > TCP > Stack Members > TCPInit Function


TCPProcess Function

Contents | Index | Home
Previous | Up | Next
TCPProcess Function
C
BOOL TCPProcess(
    NODE_INFO* remote,
    IP_ADDR* localIP,
    WORD len
);
Description

This function handles incoming TCP segments. When a segment arrives, it is compared to open sockets using a hash of the remote port and IP. On a match, the data is passed to HandleTCPSeg for further processing.

Preconditions

TCP is initialized and a TCP segment is ready in the MAC buffer.

Parameters
Parameters | Description
remote | Remote NODE_INFO structure
localIP | This stack's IP address (for header checking)
len | Total length of the waiting TCP segment
Return Values
Return Values | Description
TRUE | the segment was properly handled.
FALSE | otherwise
Stack API > TCP > Stack Members > TCPProcess Function


TCPTick Function

Contents | Index | Home
Previous | Up | Next
TCPTick Function
C
void TCPTick();
Description

This function performs any required periodic TCP tasks. Each socket's state machine is checked, and any elapsed timeout periods are handled.

Preconditions

TCP is initialized.

Returns

None

Stack API > TCP > Stack Members > TCPTick Function


TCPSSLDecryptMAC Function

Contents | Index | Home
Previous | Up | Next
TCPSSLDecryptMAC Function
C
void TCPSSLDecryptMAC(
    TCP_SOCKET hTCP,
    ARCFOUR_CTX* ctx,
    WORD len
);
Description

This function decrypts data in the TCP buffer and calculates the MAC over the data. All data is left in the exact same location in the TCP buffer. It is called to help process incoming SSL records.

Preconditions

TCP is initialized, hTCP is connected, and ctx's Sbox is loaded.

Parameters
Parameters | Description
hTCP | TCP connection to decrypt in
ctx | ARCFOUR encryption context to use
len | Number of bytes to crypt
inPlace | TRUE to write back in place, FALSE to write at end of currently visible data.
Returns

None

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Stack API > TCP > Stack Members > TCPSSLDecryptMAC Function


TCPStartSSLClientEx Function

Contents | Index | Home
Previous | Up | Next
TCPStartSSLClientEx Function
C
BOOL TCPStartSSLClientEx(
    TCP_SOCKET hTCP,
    BYTE* host,
    void * buffer,
    BYTE 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
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.

Stack API > TCP > Stack Members > TCPStartSSLClientEx Function


TCP Internal Members

Contents | Index | Home
Previous | Up | Next
TCP Internal Members

The following functions and variables are designated as internal to the TCP module.

Functions
Name | Description
CloseSocket | Closes a TCP socket.
FindMatchingSocket | Finds a suitable socket for a TCP segment.
HandleTCPSeg | Processes an incoming TCP segment.
SendTCP | Transmits a TPC segment.
SwapTCPHeader | Swaps endian-ness of a TCP header.
SyncTCB | Flushes MyTCB cache and loads up the specified TCB. Does nothing on cache hit.
Macros
Name | Description
ACK | Acknowledge Flag as defined in RFC
FIN | FIN Flag as defined in RFC
LOCAL_PORT_END_NUMBER | End port for client sockets
LOCAL_PORT_START_NUMBER | Starting port for client sockets
PSH | Push Flag as defined in RFC
RST | Reset Flag as defined in RFC
SENDTCP_KEEP_ALIVE | Instead of transmitting normal data, a garbage octet is transmitted according to RFC 1122 section 4.2.3.6
SENDTCP_RESET_TIMERS | Indicates if this packet is a retransmission (no reset) or a new packet (reset required)
SYN | SYN Flag as defined in RFC
SyncTCBStub | Flushes MyTCBStub cache and loads up the specified TCB_STUB. Does nothing on cache hit.
TCP_AUTO_TRANSMIT_TIMEOUT_VAL | Timeout before automatically transmitting unflushed data
TCP_WINDOW_UPDATE_TIMEOUT_VAL | Timeout before automatically transmitting a window update due to a TCPGet() or TCPGetArray() function call
TCP_CLOSE_WAIT_TIMEOUT | Timeout for the CLOSE_WAIT state
TCP_DELAYED_ACK_TIMEOUT | Timeout for delayed-acknowledgement algorithm
TCP_FIN_WAIT_2_TIMEOUT | Timeout for FIN WAIT 2 state
TCP_KEEP_ALIVE_TIMEOUT | Timeout for keep-alive messages when no traffic is sent
TCP_MAX_RETRIES | Maximum number of retransmission attempts
TCP_MAX_SEG_SIZE_RX | TCP Maximum Segment Size for RX. This value is advirtised during connection establishment and the remote node should obey it. This should be set to 536 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).
TCP_MAX_SEG_SIZE_TX | TCP Maximum Segment Size for TX. The TX maximum segment size is actually govered by the remote node's MSS option advirtised 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_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_OPTIMIZE_FOR_SIZE | For smallest size and best throughput, TCP_OPTIMIZE_FOR_SIZE should always be enabled on PIC24/dsPIC products. On PIC32 products there is very little difference and depnds on compiler optimization level
TCP_OPTIONS_END_OF_LIST | End of List TCP Option Flag
TCP_OPTIONS_MAX_SEG_SIZE | Maximum segment size TCP flag
TCP_OPTIONS_NO_OP | No Op TCP Option
TCP_SOCKET_COUNT | Determines the number of defined TCP sockets
TCP_START_TIMEOUT_VAL | Timeout to retransmit unacked data
TCP_SYN_QUEUE_MAX_ENTRIES | Number of TCP RX SYN packets to save if they cannot be serviced immediately
TCP_SYN_QUEUE_TIMEOUT | Timeout for when SYN queue entries are deleted if unserviceable
URG | Urgent Flag as defined in RFC
Module

TCP

Structures
Name | Description
TCP_HEADER | TCP Header Data Structure
TCP_OPTIONS | TCP Options data structure
TCP_SYN_QUEUE | Structure containing all the important elements of an incomming SYN packet in order to establish a connection at a future time if all sockets on the listening port are already connected to someone
Variables
Name | Description
hCurrentTCP | Current TCP socket
MyTCB | Currently loaded TCB
MyTCBStub | Alias to current TCP stub.
SYNQueue | Array of saved incoming SYN requests that need to be serviced later
TCBStubs | This is variable TCBStubs.
Stack API > TCP > Internal Members


ACK Macro

Contents | Index | Home
Previous | Up | Next
ACK Macro
C
#define ACK (0x10)        // Acknowledge Flag as defined in RFC
Description

Acknowledge Flag as defined in RFC

Stack API > TCP > Internal Members > ACK Macro


CloseSocket Function

Contents | Index | Home
Previous | Up | Next
CloseSocket Function
C
static void CloseSocket();
Description

This function closes a TCP socket. All socket state information is reset, and any buffered bytes are discarded. The socket is no longer accessible by the application after this point.

Preconditions

The TCPStub corresponding to the socket to be closed is synced.

Returns

None

Stack API > TCP > Internal Members > CloseSocket Function


FIN Macro

Contents | Index | Home
Previous | Up | Next
FIN Macro
C
#define FIN (0x01)        // FIN Flag as defined in RFC
Description

FIN Flag as defined in RFC

Stack API > TCP > Internal Members > FIN Macro


FindMatchingSocket Function

Contents | Index | Home
Previous | Up | Next
FindMatchingSocket Function
C
static BOOL FindMatchingSocket(
    TCP_HEADER* h,
    NODE_INFO* remote
);
Description

This function searches through the sockets and attempts to match one with a given TCP header and NODE_INFO structure. If a socket is found, its index is saved in hCurrentTCP and the associated MyTCBStub and MyTCB are loaded. Otherwise, INVALID_SOCKET is placed in hCurrentTCP.

Preconditions

TCP is initialized.

Parameters
Parameters | Description
h | TCP header to be matched against
remote | The remote node who sent this header
Return Values
Return Values | Description
TRUE | A match was found and is loaded in hCurrentTCP
FALSE | No suitable socket was found and hCurrentTCP is INVALID_SOCKET
Stack API > TCP > Internal Members > FindMatchingSocket Function


HandleTCPSeg Function

Contents | Index | Home
Previous | Up | Next
HandleTCPSeg Function
C
static void HandleTCPSeg(
    TCP_HEADER* h,
    WORD len
);
Description

Once an incoming segment has been matched to a socket, this function performs the necessary processing with the data. Depending on the segment and the state, this may include copying data to the TCP buffer, re-assembling out-of order packets, continuing an initialization or closing handshake, or closing the socket altogether.

Preconditions

TCP is initialized and the current TCP stub is already synced.

Parameters
Parameters | Description
h | The TCP header for this packet
len | The total buffer length of this segment
Returns

None

Stack API > TCP > Internal Members > HandleTCPSeg Function


hCurrentTCP Variable

Contents | Index | Home
Previous | Up | Next
hCurrentTCP Variable
C
TCP_SOCKET hCurrentTCP = INVALID_SOCKET;
Description

Current TCP socket

Stack API > TCP > Internal Members > hCurrentTCP Variable


LOCAL_PORT_END_NUMBER Macro

Contents | Index | Home
Previous | Up | Next
LOCAL_PORT_END_NUMBER Macro
C
#define LOCAL_PORT_END_NUMBER (5000u)
Description

End port for client sockets

Stack API > TCP > Internal Members > LOCAL_PORT_END_NUMBER Macro


LOCAL_PORT_START_NUMBER Macro

Contents | Index | Home
Previous | Up | Next
LOCAL_PORT_START_NUMBER Macro
C
#define LOCAL_PORT_START_NUMBER (1024u)
Description

Starting port for client sockets

Stack API > TCP > Internal Members > LOCAL_PORT_START_NUMBER Macro


MyTCB Variable

Contents | Index | Home
Previous | Up | Next
MyTCB Variable
C
TCB MyTCB;
Description

Currently loaded TCB

Stack API > TCP > Internal Members > MyTCB Variable


MyTCBStub Variable

Contents | Index | Home
Previous | Up | Next
MyTCBStub Variable
C
TCB_STUB MyTCBStub;
Description

Alias to current TCP stub.

Stack API > TCP > Internal Members > MyTCBStub Variable


PSH Macro

Contents | Index | Home
Previous | Up | Next
PSH Macro
C
#define PSH (0x08)        // Push Flag as defined in RFC
Description

Push Flag as defined in RFC

Stack API > TCP > Internal Members > PSH Macro


RST Macro

Contents | Index | Home
Previous | Up | Next
RST Macro
C
#define RST (0x04)        // Reset Flag as defined in RFC
Description

Reset Flag as defined in RFC

Stack API > TCP > Internal Members > RST Macro


SendTCP Function

Contents | Index | Home
Previous | Up | Next
SendTCP Function
C
static void SendTCP(
    BYTE vTCPFlags,
    BYTE vSendFlags
);
Description

This function assembles and transmits a TCP segment, including any pending data. It also supports retransmissions, keep-alives, and other packet types.

Preconditions

TCP is initialized.

Parameters
Parameters | Description
vTCPFlags | Additional TCP flags to include
vSendFlags | Any combinations of SENDTCP_* constants to modify the transmit behavior or contents.
Returns

None

Stack API > TCP > Internal Members > SendTCP Function


SENDTCP_KEEP_ALIVE Macro

Contents | Index | Home
Previous | Up | Next
SENDTCP_KEEP_ALIVE Macro
C
#define SENDTCP_KEEP_ALIVE 0x02
Description

Instead of transmitting normal data, a garbage octet is transmitted according to RFC 1122 section 4.2.3.6

Stack API > TCP > Internal Members > SENDTCP_KEEP_ALIVE Macro


SENDTCP_RESET_TIMERS Macro

Contents | Index | Home
Previous | Up | Next
SENDTCP_RESET_TIMERS Macro
C
#define SENDTCP_RESET_TIMERS 0x01
Description

Indicates if this packet is a retransmission (no reset) or a new packet (reset required)

Stack API > TCP > Internal Members > SENDTCP_RESET_TIMERS Macro


SwapTCPHeader Function

Contents | Index | Home
Previous | Up | Next
SwapTCPHeader Function
C
static void SwapTCPHeader(
    TCP_HEADER* header
);
Description

This function swaps the endian-ness of a given TCP header for comparison.

Preconditions

None

Parameters
Parameters | Description
header | The TCP header that is to be swapped
Returns

None

Stack API > TCP > Internal Members > SwapTCPHeader Function


SYN Macro

Contents | Index | Home
Previous | Up | Next
SYN Macro
C
#define SYN (0x02)        // SYN Flag as defined in RFC
Description

SYN Flag as defined in RFC

Stack API > TCP > Internal Members > SYN Macro


SyncTCB Function

Contents | Index | Home
Previous | Up | Next
SyncTCB Function
C
static void SyncTCB();
Description

Flushes MyTCB cache and loads up the specified TCB. Does nothing on cache hit.

Stack API > TCP > Internal Members > SyncTCB Function


SyncTCBStub Macro

Contents | Index | Home
Previous | Up | Next
SyncTCBStub Macro
C
#define SyncTCBStub(a) hCurrentTCP = (a)
Description

Flushes MyTCBStub cache and loads up the specified TCB_STUB. Does nothing on cache hit.

Stack API > TCP > Internal Members > SyncTCBStub Macro


SYNQueue Variable

Contents | Index | Home
Previous | Up | Next
SYNQueue Variable
C
TCP_SYN_QUEUE SYNQueue[TCP_SYN_QUEUE_MAX_ENTRIES];
Description

Array of saved incoming SYN requests that need to be serviced later

Stack API > TCP > Internal Members > SYNQueue Variable


TCBStubs Variable

Contents | Index | Home
Previous | Up | Next
TCBStubs Variable
C
TCB_STUB TCBStubs[TCP_SOCKET_COUNT];
Description

This is variable TCBStubs.

Stack API > TCP > Internal Members > TCBStubs Variable


TCP_AUTO_TRANSMIT_TIMEOUT_VAL Macro

Contents | Index | Home
Previous | Up | Next
TCP_AUTO_TRANSMIT_TIMEOUT_VAL Macro
C
#define TCP_AUTO_TRANSMIT_TIMEOUT_VAL (TICK_SECOND/25ull)    // Timeout before automatically transmitting unflushed data
Description

Timeout before automatically transmitting unflushed data

Stack API > TCP > Internal Members > TCP_AUTO_TRANSMIT_TIMEOUT_VAL Macro


TCP_WINDOW_UPDATE_TIMEOUT_VAL Macro

Contents | Index | Home
Previous | Up | Next
TCP_WINDOW_UPDATE_TIMEOUT_VAL Macro
C
#define TCP_WINDOW_UPDATE_TIMEOUT_VAL (TICK_SECOND/5ull)    // Timeout before automatically transmitting a window update due to a TCPGet() or TCPGetArray() function call
Description

Timeout before automatically transmitting a window update due to a TCPGet() or TCPGetArray() function call

Stack API > TCP > Internal Members > TCP_WINDOW_UPDATE_TIMEOUT_VAL Macro


TCP_CLOSE_WAIT_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
TCP_CLOSE_WAIT_TIMEOUT Macro
C
#define TCP_CLOSE_WAIT_TIMEOUT ((DWORD)TICK_SECOND/5)    // Timeout for the CLOSE_WAIT state
Description

Timeout for the CLOSE_WAIT state

Stack API > TCP > Internal Members > TCP_CLOSE_WAIT_TIMEOUT Macro


TCP_DELAYED_ACK_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
TCP_DELAYED_ACK_TIMEOUT Macro
C
#define TCP_DELAYED_ACK_TIMEOUT ((DWORD)TICK_SECOND/10)    // Timeout for delayed-acknowledgement algorithm
Description

Timeout for delayed-acknowledgement algorithm

Stack API > TCP > Internal Members > TCP_DELAYED_ACK_TIMEOUT Macro


TCP_FIN_WAIT_2_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
TCP_FIN_WAIT_2_TIMEOUT Macro
C
#define TCP_FIN_WAIT_2_TIMEOUT ((DWORD)TICK_SECOND*5)    // Timeout for FIN WAIT 2 state
Description

Timeout for FIN WAIT 2 state

Stack API > TCP > Internal Members > TCP_FIN_WAIT_2_TIMEOUT Macro


TCP_HEADER Structure

Contents | Index | Home
Previous | Up | Next
TCP_HEADER Structure
C
typedef struct {
  WORD SourcePort;
  WORD DestPort;
  DWORD SeqNumber;
  DWORD AckNumber;
  struct {
    unsigned char Reserved3 : 4;
    unsigned char Val : 4;
  } DataOffset;
  union {
    struct {
      unsigned char flagFIN : 1;
      unsigned char flagSYN : 1;
      unsigned char flagRST : 1;
      unsigned char flagPSH : 1;
      unsigned char flagACK : 1;
      unsigned char flagURG : 1;
      unsigned char Reserved2 : 2;
    } bits;
    BYTE byte;
  } Flags;
  WORD Window;
  WORD Checksum;
  WORD UrgentPointer;
} TCP_HEADER;
Description

TCP Header Data Structure

Members
Members
Description
WORD SourcePort;
Local port number
WORD DestPort;
Remote port number
DWORD SeqNumber;
Local sequence number
DWORD AckNumber;
Acknowledging remote sequence number
struct {
unsigned char Reserved3 : 4;
unsigned char Val : 4;
} DataOffset;
Data offset flags nibble
union {
struct {
unsigned char flagFIN : 1;
unsigned char flagSYN : 1;
unsigned char flagRST : 1;
unsigned char flagPSH : 1;
unsigned char flagACK : 1;
unsigned char flagURG : 1;
unsigned char Reserved2 : 2;
} bits;
BYTE byte;
} Flags;
TCP Flags as defined in RFC
WORD Window;
Local free RX buffer window
WORD Checksum;
Data payload checksum
WORD UrgentPointer;
Urgent pointer
Stack API > TCP > Internal Members > TCP_HEADER Structure


TCP_KEEP_ALIVE_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
TCP_KEEP_ALIVE_TIMEOUT Macro
C
#define TCP_KEEP_ALIVE_TIMEOUT ((DWORD)TICK_SECOND*10)    // Timeout for keep-alive messages when no traffic is sent
Description

Timeout for keep-alive messages when no traffic is sent

Stack API > TCP > Internal Members > TCP_KEEP_ALIVE_TIMEOUT Macro


TCP_MAX_RETRIES Macro

Contents | Index | Home
Previous | Up | Next
TCP_MAX_RETRIES Macro
C
#define TCP_MAX_RETRIES (5u)                    // Maximum number of retransmission attempts
Description

Maximum number of retransmission attempts

Stack API > TCP > Internal Members > TCP_MAX_RETRIES Macro


TCP_MAX_SEG_SIZE_RX Macro

Contents | Index | Home
Previous | Up | Next
TCP_MAX_SEG_SIZE_RX Macro
C
#define TCP_MAX_SEG_SIZE_RX (536u)
Description

TCP Maximum Segment Size for RX. This value is advirtised during connection establishment and the remote node should obey it. This should be set to 536 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).

Stack API > TCP > Internal Members > TCP_MAX_SEG_SIZE_RX Macro


TCP_MAX_SEG_SIZE_TX Macro

Contents | Index | Home
Previous | Up | Next
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 govered by the remote node's MSS option advirtised 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.

Stack API > TCP > Internal Members > TCP_MAX_SEG_SIZE_TX Macro


TCP_MAX_SYN_RETRIES Macro

Contents | Index | Home
Previous | Up | Next
TCP_MAX_SYN_RETRIES Macro
C
#define TCP_MAX_SYN_RETRIES (2u)    // Smaller than all other retries to reduce SYN flood DoS duration
Description

Smaller than all other retries to reduce SYN flood DoS duration

Stack API > TCP > Internal Members > TCP_MAX_SYN_RETRIES Macro


TCP_MAX_UNACKED_KEEP_ALIVES Macro

Contents | Index | Home
Previous | Up | Next
TCP_MAX_UNACKED_KEEP_ALIVES Macro
C
#define TCP_MAX_UNACKED_KEEP_ALIVES (6u)                    // Maximum number of keep-alive messages that can be sent without receiving a response before automatically closing the connection
Description

Maximum number of keep-alive messages that can be sent without receiving a response before automatically closing the connection

Stack API > TCP > Internal Members > TCP_MAX_UNACKED_KEEP_ALIVES Macro


TCP_OPTIMIZE_FOR_SIZE Macro

Contents | Index | Home
Previous | Up | Next
TCP_OPTIMIZE_FOR_SIZE Macro
C
#define TCP_OPTIMIZE_FOR_SIZE
Description

For smallest size and best throughput, TCP_OPTIMIZE_FOR_SIZE should always be enabled on PIC24/dsPIC products. On PIC32 products there is very little difference and depnds on compiler optimization level

Stack API > TCP > Internal Members > TCP_OPTIMIZE_FOR_SIZE Macro


TCP_OPTIONS Structure

Contents | Index | Home
Previous | Up | Next
TCP_OPTIONS Structure
C
typedef struct {
  BYTE Kind;
  BYTE Length;
  WORD_VAL MaxSegSize;
} TCP_OPTIONS;
Description

TCP Options data structure

Members
Members | Description
BYTE Kind; | Type of option
BYTE Length; | Length
WORD_VAL MaxSegSize; | Maximum segment size
Stack API > TCP > Internal Members > TCP_OPTIONS Structure


TCP_OPTIONS_END_OF_LIST Macro

Contents | Index | Home
Previous | Up | Next
TCP_OPTIONS_END_OF_LIST Macro
C
#define TCP_OPTIONS_END_OF_LIST (0x00u)        // End of List TCP Option Flag
Description

End of List TCP Option Flag

Stack API > TCP > Internal Members > TCP_OPTIONS_END_OF_LIST Macro


TCP_OPTIONS_MAX_SEG_SIZE Macro

Contents | Index | Home
Previous | Up | Next
TCP_OPTIONS_MAX_SEG_SIZE Macro
C
#define TCP_OPTIONS_MAX_SEG_SIZE (0x02u)        // Maximum segment size TCP flag
Description

Maximum segment size TCP flag

Stack API > TCP > Internal Members > TCP_OPTIONS_MAX_SEG_SIZE Macro


TCP_OPTIONS_NO_OP Macro

Contents | Index | Home
Previous | Up | Next
TCP_OPTIONS_NO_OP Macro
C
#define TCP_OPTIONS_NO_OP (0x01u)        // No Op TCP Option
Description

No Op TCP Option

Stack API > TCP > Internal Members > TCP_OPTIONS_NO_OP Macro


TCP_SOCKET_COUNT Macro

Contents | Index | Home
Previous | Up | Next
TCP_SOCKET_COUNT Macro
C
#define TCP_SOCKET_COUNT (sizeof(TCPSocketInitializer)/sizeof(TCPSocketInitializer[0]))
Description

Determines the number of defined TCP sockets

Stack API > TCP > Internal Members > TCP_SOCKET_COUNT Macro


TCP_START_TIMEOUT_VAL Macro

Contents | Index | Home
Previous | Up | Next
TCP_START_TIMEOUT_VAL Macro
C
#define TCP_START_TIMEOUT_VAL ((DWORD)TICK_SECOND*1)    // Timeout to retransmit unacked data
Description

Timeout to retransmit unacked data

Stack API > TCP > Internal Members > TCP_START_TIMEOUT_VAL Macro


TCP_SYN_QUEUE Structure

Contents | Index | Home
Previous | Up | Next
TCP_SYN_QUEUE Structure
C
typedef struct {
  NODE_INFO niSourceAddress;
  WORD wSourcePort;
  DWORD dwSourceSEQ;
  WORD wDestPort;
  WORD wTimestamp;
} TCP_SYN_QUEUE;
Description

Structure containing all the important elements of an incomming SYN packet in order to establish a connection at a future time if all sockets on the listening port are already connected to someone

Members
Members | Description
NODE_INFO niSourceAddress; | Remote IP address and MAC address
WORD wSourcePort; | Remote TCP port number that the response SYN needs to be sent to
DWORD dwSourceSEQ; | Remote TCP SEQuence number that must be ACKnowledged when we send our response SYN
WORD wDestPort; | Local TCP port which the original SYN was destined for
WORD wTimestamp; | Timer to expire old SYN packets that can't be serviced at all
Stack API > TCP > Internal Members > TCP_SYN_QUEUE Structure


TCP_SYN_QUEUE_MAX_ENTRIES Macro

Contents | Index | Home
Previous | Up | Next
TCP_SYN_QUEUE_MAX_ENTRIES Macro
C
#define TCP_SYN_QUEUE_MAX_ENTRIES (3u)                    // Number of TCP RX SYN packets to save if they cannot be serviced immediately
Description

Number of TCP RX SYN packets to save if they cannot be serviced immediately

Stack API > TCP > Internal Members > TCP_SYN_QUEUE_MAX_ENTRIES Macro


TCP_SYN_QUEUE_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
TCP_SYN_QUEUE_TIMEOUT Macro
C
#define TCP_SYN_QUEUE_TIMEOUT ((DWORD)TICK_SECOND*3)    // Timeout for when SYN queue entries are deleted if unserviceable
Description

Timeout for when SYN queue entries are deleted if unserviceable

Stack API > TCP > Internal Members > TCP_SYN_QUEUE_TIMEOUT Macro


URG Macro

Contents | Index | Home
Previous | Up | Next
URG Macro
C
#define URG (0x20)        // Urgent Flag as defined in RFC
Description

Urgent Flag as defined in RFC

Stack API > TCP > Internal Members > URG Macro


Variables

Contents | Index | Home
Previous | Up | Next
Variables
Module

TCP

Variables
Name | Description
NextPort | Tracking variable for next local client port number
Stack API > TCP > Variables


NextPort Variable

Contents | Index | Home
Previous | Up | Next
NextPort Variable
C
WORD NextPort;
Description

Tracking variable for next local client port number

Stack API > TCP > Variables > NextPort Variable


TFTP

Contents | Index | Home
Previous | Up | Next
TFTP

The Trivial File Transfer Protocol provides unreliable upload and download services to applications connected to the UDP-based TFTP server.

Topics
Name | Description
TFTP Public Members | Functions and variables accessible by the stack application.
TFTP Stack Members | Functions and variables intended to be accessed only by the stack
TFTP Internal Members | Functions and variables internal to the TFTP module
Stack API > TFTP


TFTP Public Members

Contents | Index | Home
Previous | Up | Next
TFTP Public Members

The following functions and variables are available to the stack application.

Enumerations
Name | Description
TFTP_ACCESS_ERROR | Standard error codes as defined by TFTP spec. Use to decode value retuned by TFTPGetError().
_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_FILE_MODE | File open mode as used by TFTPFileOpen().
TFTP_RESULT | Enum. of results returned by most of the TFTP functions.
_TFTP_RESULT | Enum. of results returned by most of the TFTP functions.
Functions
Name | Description
TFTPCloseFile | Sends file closing messages.
TFTPGet | Gets a data byte from data that was read.
TFTPIsFileClosed | Determines if the file was closed.
TFTPIsFileOpened | Determines if file has been opened.
TFTPIsGetReady | Determines if a data block is ready to be read.
TFTPIsOpened | Determines if the TFTP connection is open.
TFTPIsPutReady | Determines if data can be written to a file.
TFTPOpen | Initializes TFTP module.
TFTPOpenFile | Prepares and sends TFTP file name and mode packet.
TFTPOpenROMFile | PIC18 ROM argument implementation of TFTPOpenFile
TFTPPut | Write a byte to a file.
TFTPGetUploadStatus | Returns the TFTP file upload status started by calling the TFTPUploadRAMFileToHost() or TFTPUploadFragmentedRAMFileToHost() functions.
TFTPUploadFragmentedRAMFileToHost | Uploads an random, potentially non-contiguous, array of RAM bytes as a file to a remote TFTP server.
TFTPUploadRAMFileToHost | Uploads a contiguous array of RAM bytes as a file to a remote TFTP server.
Macros
Name | Description
TFTPClose | Macro: void TFTPClose(void) Closes TFTP client socket.
TFTPGetError | Macro: WORD 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_UPLOAD_COMPLETE | Status codes for TFTPGetUploadStatus() 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.
Module

TFTP

Structures
Name | Description
TFTP_CHUNK_DESCRIPTOR | This is type TFTP_CHUNK_DESCRIPTOR.
Stack API > TFTP > Public Members


TFTPClose Macro

Contents | Index | Home
Previous | Up | Next
TFTPClose Macro
C
#define TFTPClose(void) UDPClose(_tftpSocket)
Description

Macro: void TFTPClose(void)

Closes TFTP client socket.

Preconditions

TFTPOpen is already called and TFTPIsOpened() returned TFTP_OK.

Returns

None

Side Effects

None

Remarks

Once closed, application must do TFTPOpen 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.

Stack API > TFTP > Public Members > TFTPClose Macro


TFTPCloseFile Function

Contents | Index | Home
Previous | Up | Next
TFTPCloseFile Function
C
void TFTPCloseFile();
Description

If file is opened in read mode, it makes sure that last ACK is sent to server If file is opened in write mode, it makes sure that last block is sent out to server and waits for server to respond with ACK.

Preconditions

TFTPOpenFile() was called and TFTPIsFileOpened() had returned with TFTP_OK.

Returns

None

Side Effects

None

Remarks

TFTPIsFileClosed() must be called to confirm if file was really closed.

Stack API > TFTP > Public Members > TFTPCloseFile Function


TFTPGet Function

Contents | Index | Home
Previous | Up | Next
TFTPGet Function
C
BYTE TFTPGet();
Description

Fetches next data byte from TFTP socket. If end of data block is reached, it issues ack to server so that next data block can be received.

Preconditions

TFTPOpenFile() is called with TFTP_FILE_MODE_READ and TFTPIsGetReady() = TRUE

Returns

data byte as received from remote server.

Side Effects

None

Remarks

Use this function to read file from server.

Stack API > TFTP > Public Members > TFTPGet Function


TFTPGetError Macro

Contents | Index | Home
Previous | Up | Next
TFTPGetError Macro
C
#define TFTPGetError (_tftpError)
Description

Macro: WORD 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

Stack API > TFTP > Public Members > TFTPGetError Macro


TFTPIsFileClosed Function

Contents | Index | Home
Previous | Up | Next
TFTPIsFileClosed Function
C
TFTP_RESULT TFTPIsFileClosed();
Description

If file mode is Read, it simply makes that last block is acknowledged. If file mode is Write, it waits for server ack. If no ack was received within specified timeout instructs appliaction to resend last block. It keeps track of retries and declares timeout all attempts were exhausted.

Preconditions

TFTPCloseFile() is already called.

Returns

TFTP_OK if file was successfully closdd

TFTP_RETRY if file mode was Write and remote server did not receive last packet. Application must retry with last block.

TFTP_TIMEOUT if all attempts were exhausted in closing file.

TFTP_ERROR if remote server sent an error in response to last block. Actual error code may be read by calling TFTPGetError()

TFTP_NOT_READY if file is not closed yet.

Side Effects

None

Remarks

None

Stack API > TFTP > Public Members > TFTPIsFileClosed Function


TFTPIsFileOpened Function

Contents | Index | Home
Previous | Up | Next
TFTPIsFileOpened Function
C
TFTP_RESULT TFTPIsFileOpened();
Description

Waits for remote server response regarding previous attempt to open file. If no response is received within specified timeout, fnction returns with TFTP_RETRY and application logic must issue another TFTPFileOpen().

Preconditions

TFTPOpenFile() is called.

Returns

TFTP_OK if file is ready to be read or written

TFTP_RETRY if previous attempt was timed out needs to be retried.

TFTP_TIMEOUT if all attempts were exhausted.

TFTP_ERROR if remote server responded with error

TFTP_NOT_READY if file is not yet opened.

Side Effects

None

Remarks

None

Stack API > TFTP > Public Members > TFTPIsFileOpened Function


TFTPIsFileOpenReady Macro

Contents | Index | Home
Previous | Up | Next
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

TFTPOpen is already called and TFTPIsOpened() returned TFTP_OK.

Returns

TRUE, if it is ok to call TFTPOpenFile() FALSE, if otherwise.

Side Effects

None

Remarks

None

Stack API > TFTP > Public Members > TFTPIsFileOpenReady Macro


TFTPIsGetReady Function

Contents | Index | Home
Previous | Up | Next
TFTPIsGetReady Function
C
TFTP_RESULT TFTPIsGetReady();
Description

Waits for data block. If data block does not arrive within specified timeout, it automatically sends out ack for previous block to remind server to send next data block. If all attempts are exhausted, it returns with TFTP_TIMEOUT.

Preconditions

TFTPOpenFile() is called with TFTP_FILE_MODE_READ and TFTPIsFileOpened() returned with TRUE.

Returns

TFTP_OK if it there is more data byte available to read

TFTP_TIMEOUT if timeout occurred waiting for new data.

TFTP_END_OF_FILE if end of file has reached.

TFTP_ERROR if remote server returned ERROR. Actual error code may be read by calling TFTPGetError()

TFTP_NOT_READY if still waiting for new data.

Side Effects

None

Remarks

By default, this funciton uses "octet" or binary mode of file transfer.

Stack API > TFTP > Public Members > TFTPIsGetReady Function


TFTPIsOpened Function

Contents | Index | Home
Previous | Up | Next
TFTPIsOpened Function
C
TFTP_RESULT TFTPIsOpened();
Description

Waits for ARP reply and opens a UDP socket to perform further TFTP operations.

Preconditions

TFTPOpen() is already called.

Returns

TFTP_OK if previous call to TFTPOpen is complete

TFTP_TIMEOUT if remote host did not respond to previous ARP request.

TFTP_NOT_READY if remote has still not responded and timeout has not expired.

Side Effects

None

Remarks

Once opened, application may keep TFTP socket open and future TFTP operations. If TFTPClose() is called to close the connection TFTPOpen() must be called again before performing any other TFTP operations.

Stack API > TFTP > Public Members > TFTPIsOpened Function


TFTPIsPutReady Function

Contents | Index | Home
Previous | Up | Next
TFTPIsPutReady Function
C
TFTP_RESULT TFTPIsPutReady();
Description

Waits for ack from server. If ack does not arrive within specified timeout, it it instructs application to retry last block by returning TFTP_RETRY.

If all attempts are exhausted, it returns with TFTP_TIMEOUT.

Preconditions

TFTPOpenFile() is called with TFTP_FILE_MODE_WRITE and TFTPIsFileOpened() returned with TRUE.

Returns

TFTP_OK if it is okay to write more data byte.

TFTP_TIMEOUT if timeout occurred waiting for ack from server

TFTP_RETRY if all server did not send ack on time and application needs to resend last block.

TFTP_ERROR if remote server returned ERROR. Actual error code may be read by calling TFTPGetError()

TFTP_NOT_READY if still waiting...

Side Effects

None

Remarks

None

Stack API > TFTP > Public Members > TFTPIsPutReady Function


TFTPOpen Function

Contents | Index | Home
Previous | Up | Next
TFTPOpen Function
C
void TFTPOpen(
    IP_ADDR * host
);
Description

Initiates ARP for given host and prepares TFTP module for next sequence of function calls.

Preconditions

UDP module is already initialized and at least one UDP socket is available.

Parameters
Parameters | Description
host | IP address of remote TFTP server
Returns

None

Side Effects

None

Remarks

Use TFTPIsOpened() to check if a connection was successfully opened or not.

Stack API > TFTP > Public Members > TFTPOpen Function


TFTPOpenFile Function

Contents | Index | Home
Previous | Up | Next
TFTPOpenFile Function
C
void TFTPOpenFile(
    BYTE * fileName,
    TFTP_FILE_MODE mode
);
Description

Prepares and sends TFTP file name and mode packet.

Preconditions

TFPTIsFileOpenReady() = TRUE

Parameters
Parameters | Description
fileName | File name that is to be opened.
mode | Mode of file access Must be TFTP_FILE_MODE_READ for read TFTP_FILE_MODE_WRITE for write
Returns

None

Side Effects

None

Remarks

By default, this funciton uses "octet" or binary mode of file transfer. Use TFTPIsFileOpened() to check if file is ready to be read or written.

Stack API > TFTP > Public Members > TFTPOpenFile Function


TFTPOpenROMFile Function

Contents | Index | Home
Previous | Up | Next
TFTPOpenROMFile Function
C
void TFTPOpenROMFile(
    ROM BYTE * fileName,
    TFTP_FILE_MODE mode
);
Description

PIC18 ROM argument implementation of TFTPOpenFile

Stack API > TFTP > Public Members > TFTPOpenROMFile Function


TFTPPut Function

Contents | Index | Home
Previous | Up | Next
TFTPPut Function
C
void TFTPPut(
    BYTE c
);
Description

Puts given data byte into TFTP socket. If end of data block is reached, it transmits entire block.

Preconditions

TFTPOpenFile() is called with TFTP_FILE_MODE_WRITE and TFTPIsPutReady() = TRUE

Parameters
Parameters | Description
c | Data byte that is to be written
Returns

None

Side Effects

None

Remarks

Use this function to write file to server.

Stack API > TFTP > Public Members > TFTPPut Function


TFTP_ACCESS_ERROR Enumeration

Contents | Index | Home
Previous | Up | Next
TFTP_ACCESS_ERROR Enumeration
C
typedef enum _TFTP_ACCESS_ERROR {
  TFTP_ERROR_NOT_DEFINED = 0,
  TFTP_ERROR_FILE_NOT_FOUND,
  TFTP_ERROR_ACCESS_VIOLATION,
  TFTP_ERROR_DISK_FULL,
  TFTP_ERROR_INVALID_OPERATION,
  TFTP_ERROR_UNKNOWN_TID,
  TFTP_ERROR_FILE_EXISTS,
  TFTP_ERROR_NO_SUCH_USE
} TFTP_ACCESS_ERROR;
Description

Standard error codes as defined by TFTP spec. Use to decode value retuned by TFTPGetError().

Stack API > TFTP > Public Members > TFTP_ACCESS_ERROR Enumeration


TFTP_FILE_MODE Enumeration

Contents | Index | Home
Previous | Up | Next
TFTP_FILE_MODE Enumeration
C
typedef enum _TFTP_FILE_MODE {
  TFTP_FILE_MODE_READ = 1,
  TFTP_FILE_MODE_WRITE = 2
} TFTP_FILE_MODE;
Description

File open mode as used by TFTPFileOpen().

Stack API > TFTP > Public Members > TFTP_FILE_MODE Enumeration


TFTP_RESULT Enumeration

Contents | Index | Home
Previous | Up | Next
TFTP_RESULT Enumeration
C
typedef enum _TFTP_RESULT {
  TFTP_OK = 0,
  TFTP_NOT_READY,
  TFTP_END_OF_FILE,
  TFTP_ERROR,
  TFTP_RETRY,
  TFTP_TIMEOUT
} TFTP_RESULT;
Description

Enum. of results returned by most of the TFTP functions.

Stack API > TFTP > Public Members > TFTP_RESULT Enumeration


TFTPGetUploadStatus Function

Contents | Index | Home
Previous | Up | Next
TFTPGetUploadStatus Function
C
CHAR TFTPGetUploadStatus();
Description

Returns the TFTP file upload status started by calling the TFTPUploadRAMFileToHost() or TFTPUploadFragmentedRAMFileToHost() functions.

Preconditions

None

Returns

A status code. Negative results are fatal errors. Positive results indicate the TFTP upload operation is still being processed. A zero result indicates successful file upload completion (TFTP API is now idle and available for further calls). Specific return values are as follows: 0 (TFTP_UPLOAD_COMPLETE): Upload completed successfully 1 (TFTP_UPLOAD_GET_DNS): Attempting to obtain DNS client module 2 (TFTP_UPLOAD_RESOLVE_HOST): Attempting to resolve TFTP hostname 3 (TFTP_UPLOAD_CONNECT): Attempting to ARP and contact the TFTP server 4 (TFTP_UPLOAD_SEND_FILENAME): Attempting to send the filename and receive acknowledgement. 5 (TFTP_UPLOAD_SEND_DATA): Attempting to send the file contents and receive acknowledgement. 6 (TFTP_UPLOAD_WAIT_FOR_CLOSURE): Attempting to send the final packet of file contents and receive acknowledgement. -1 (TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT): Couldn't resolve hostname -2 (TFTP_UPLOAD_CONNECT_TIMEOUT): Couldn't finish ARP and reach server -3 (TFTP_UPLOAD_SERVER_ERROR): TFTP server returned an error (ex: access denial) or file upload failed due to a timeout (partial file may have been uploaded).

Remarks

The DNS client module must be enabled to use this function. i.e. STACK_USE_DNS must be defined in TCPIPConfig.h.

Stack API > TFTP > Public Members > TFTPGetUploadStatus Function


TFTPUploadFragmentedRAMFileToHost Function

Contents | Index | Home
Previous | Up | Next
TFTPUploadFragmentedRAMFileToHost Function
C
void TFTPUploadFragmentedRAMFileToHost(
    ROM BYTE * vRemoteHost,
    ROM BYTE * vFilename,
    TFTP_CHUNK_DESCRIPTOR * vFirstChunkDescriptor
);
Description

Uploads an random, potentially non-contiguous, array of RAM bytes as a file to a remote TFTP server.

Preconditions

None

Parameters
Parameters | Description
vRemoteHost | ROM string of the remote TFTP server to upload to (ex: "www.myserver.com"). For device architectures that make no distinction between RAM and ROM pointers (PIC24, dsPIC and PIC32), this string must remain allocated and unmodified in RAM until the TFTP upload process completes (as indicated by TFTPGetUploadStatus()).
vFilename | ROM string of the remote file to create/overwrite (ex: "status.txt"). For device architectures that make no distinction between RAM and ROM pointers (PIC24, dsPIC and PIC32), this string must remain allocated and unmodified in RAM until the TFTP upload process completes (as indicated by TFTPGetUploadStatus()).
vFirstChunkDescriptor | Pointer to a static or global (persistent) array of TFTP_CHUNK_DESCRIPTOR structures describing what RAM memory addresses the file contents should be obtained from. The TFTP_CHUNK_DESCRIPTOR.vDataPointer field should be set to the memory address of the data to transmit, and the TFTP_CHUNK_DESCRIPTOR.wDataLength field should be set to the number of bytes to transmit from the given pointer. The TFTP_CHUNK_DESCRIPTOR array must be terminated by a dummy descriptor whos TFTP_CHUNK_DESCRIPTOR.vDataPointer pointer is set to NULL. Refer to the TFTPUploadRAMFileToHost() API for an example calling sequence since it merely a wrapper to this TFTPUploadFragmentedRAMFileToHost() function.
Returns

None

Remarks

The DNS client module must be enabled to use this function. i.e. STACK_USE_DNS must be defined in TCPIPConfig.h.

Call the TFTPGetUploadStatus() function to determine the status of the file upload.

It is only possible to have one TFTP operation active at any given time. After starting a TFTP operation by calling TFTPUploadRAMFileToHost() or TFTPUploadFragmentedRAMFileToHost(), you must wait until TFTPGetUploadStatus() returns a completion status code (<=0) before calling any other TFTP API functions.

Stack API > TFTP > Public Members > TFTPUploadFragmentedRAMFileToHost Function


TFTPUploadRAMFileToHost Function

Contents | Index | Home
Previous | Up | Next
TFTPUploadRAMFileToHost Function
C
void TFTPUploadRAMFileToHost(
    ROM BYTE * vRemoteHost,
    ROM BYTE * vFilename,
    BYTE * vData,
    WORD wDataLength
);
Description

Uploads a contiguous array of RAM bytes as a file to a remote TFTP server.

Preconditions

None

Parameters
Parameters | Description
vRemoteHost | ROM string of the remote TFTP server to upload to (ex: "www.myserver.com"). For device architectures that make no distinction between RAM and ROM pointers (PIC24, dsPIC and PIC32), this string must remain allocated and unmodified in RAM until the TFTP upload process completes (as indicated by TFTPGetUploadStatus()).
vFilename | ROM string of the remote file to create/overwrite (ex: "status.txt"). For device architectures that make no distinction between RAM and ROM pointers (PIC24, dsPIC and PIC32), this string must remain allocated and unmodified in RAM until the TFTP upload process completes (as indicated by TFTPGetUploadStatus()).
vData | Pointer to a RAM array of data to write to the file.
wDataLength | Number of bytes pointed to by vData. This will be the final file size of the uploaded file. Note that since this is defined as a WORD type, the maximum possible file size is 65535 bytes. For longer files, call the TFTPUploadFragmentedRAMFileToHost() function instead.
Returns

None

Remarks

The DNS client module must be enabled to use this function. i.e. STACK_USE_DNS must be defined in TCPIPConfig.h.

Call the TFTPGetUploadStatus() function to determine the status of the file upload.

It is only possible to have one TFTP operation active at any given time. After starting a TFTP operation by calling TFTPUploadRAMFileToHost() or TFTPUploadFragmentedRAMFileToHost(), you must wait until TFTPGetUploadStatus() returns a completion status code (<=0) before calling any other TFTP API functions.

Stack API > TFTP > Public Members > TFTPUploadRAMFileToHost Function


TFTP_CHUNK_DESCRIPTOR Structure

Contents | Index | Home
Previous | Up | Next
TFTP_CHUNK_DESCRIPTOR Structure
C
typedef struct {
  BYTE * vDataPointer;
  WORD wDataLength;
} TFTP_CHUNK_DESCRIPTOR;
Description

This is type TFTP_CHUNK_DESCRIPTOR.

Stack API > TFTP > Public Members > TFTP_CHUNK_DESCRIPTOR Structure


TFTP_UPLOAD_COMPLETE Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_COMPLETE Macro
C
#define TFTP_UPLOAD_COMPLETE 0
Description

Status codes for TFTPGetUploadStatus() function. Zero means upload success, >0 means working and <0 means fatal error.

Stack API > TFTP > Public Members > TFTP_UPLOAD_COMPLETE Macro


TFTP_UPLOAD_CONNECT Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_CONNECT Macro
C
#define TFTP_UPLOAD_CONNECT 3
Description

This is macro TFTP_UPLOAD_CONNECT.

Stack API > TFTP > Public Members > TFTP_UPLOAD_CONNECT Macro


TFTP_UPLOAD_CONNECT_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_CONNECT_TIMEOUT Macro
C
#define TFTP_UPLOAD_CONNECT_TIMEOUT -2
Description

This is macro TFTP_UPLOAD_CONNECT_TIMEOUT.

Stack API > TFTP > Public Members > TFTP_UPLOAD_CONNECT_TIMEOUT Macro


TFTP_UPLOAD_GET_DNS Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_GET_DNS Macro
C
#define TFTP_UPLOAD_GET_DNS 1
Description

This is macro TFTP_UPLOAD_GET_DNS.

Stack API > TFTP > Public Members > TFTP_UPLOAD_GET_DNS Macro


TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT Macro
C
#define TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT -1
Description

This is macro TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT.

Stack API > TFTP > Public Members > TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT Macro


TFTP_UPLOAD_RESOLVE_HOST Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_RESOLVE_HOST Macro
C
#define TFTP_UPLOAD_RESOLVE_HOST 2
Description

This is macro TFTP_UPLOAD_RESOLVE_HOST.

Stack API > TFTP > Public Members > TFTP_UPLOAD_RESOLVE_HOST Macro


TFTP_UPLOAD_SEND_DATA Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_SEND_DATA Macro
C
#define TFTP_UPLOAD_SEND_DATA 5
Description

This is macro TFTP_UPLOAD_SEND_DATA.

Stack API > TFTP > Public Members > TFTP_UPLOAD_SEND_DATA Macro


TFTP_UPLOAD_SEND_FILENAME Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_SEND_FILENAME Macro
C
#define TFTP_UPLOAD_SEND_FILENAME 4
Description

This is macro TFTP_UPLOAD_SEND_FILENAME.

Stack API > TFTP > Public Members > TFTP_UPLOAD_SEND_FILENAME Macro


TFTP_UPLOAD_SERVER_ERROR Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_SERVER_ERROR Macro
C
#define TFTP_UPLOAD_SERVER_ERROR -3
Description

This is macro TFTP_UPLOAD_SERVER_ERROR.

Stack API > TFTP > Public Members > TFTP_UPLOAD_SERVER_ERROR Macro


TFTP_UPLOAD_WAIT_FOR_CLOSURE Macro

Contents | Index | Home
Previous | Up | Next
TFTP_UPLOAD_WAIT_FOR_CLOSURE Macro
C
#define TFTP_UPLOAD_WAIT_FOR_CLOSURE 6
Description

This is macro TFTP_UPLOAD_WAIT_FOR_CLOSURE.

Stack API > TFTP > Public Members > TFTP_UPLOAD_WAIT_FOR_CLOSURE Macro


TFTP Stack Members

Contents | Index | Home
Previous | Up | Next
TFTP Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Macros
Name | Description
TFTP_ARP_TIMEOUT_VAL | Number of seconds to wait before declaring TIMEOUT error on Put
TFTP_GET_TIMEOUT_VAL | Number of seconds to wait before declaring TIMEOUT error on Get.
TFTP_MAX_RETRIES | Number of attempts before declaring TIMEOUT error.
Module

TFTP

Stack API > TFTP > Stack Members


TFTP_ARP_TIMEOUT_VAL Macro

Contents | Index | Home
Previous | Up | Next
TFTP_ARP_TIMEOUT_VAL Macro
C
#define TFTP_ARP_TIMEOUT_VAL (3u * TICKS_PER_SECOND)
Description

Number of seconds to wait before declaring TIMEOUT error on Put

Stack API > TFTP > Stack Members > TFTP_ARP_TIMEOUT_VAL Macro


TFTP_GET_TIMEOUT_VAL Macro

Contents | Index | Home
Previous | Up | Next
TFTP_GET_TIMEOUT_VAL Macro
C
#define TFTP_GET_TIMEOUT_VAL (3u * TICKS_PER_SECOND)
Description

Number of seconds to wait before declaring TIMEOUT error on Get.

Stack API > TFTP > Stack Members > TFTP_GET_TIMEOUT_VAL Macro


TFTP_MAX_RETRIES Macro

Contents | Index | Home
Previous | Up | Next
TFTP_MAX_RETRIES Macro
C
#define TFTP_MAX_RETRIES (3u)
Description

Number of attempts before declaring TIMEOUT error.

Stack API > TFTP > Stack Members > TFTP_MAX_RETRIES Macro


TFTP Internal Members

Contents | Index | Home
Previous | Up | Next
TFTP Internal Members

The following functions and variables are designated as internal to the TFTP module.

Enumerations
Name | Description
TFTP_OPCODE | Enumeration of TFTP opcodes
TFTP_STATE | The TFTP state machine
Functions
Name | Description
_TFTPSendAck | Private helper function
_TFTPSendFileName | Private helper function
_TFTPSendROMFileName | PIC18 ROM variable argument implementation of _TFTPSendFileName
Macros
Name | Description
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_SERVER_PORT | The TFTP Server Port
Module

TFTP

Variables
Name | Description
MutExVar | Mutually Exclusive variable groups to conserve RAM.
_tftpError | Variable to preserve error condition causes for later transmission
_tftpFlags | TFTP status flags
_tftpRetries | Tracker variable for the number of TFTP retries
_tftpSocket | TFTP Socket for TFTP server link
_tftpStartTick | Timing variable used to detect timeout conditions
_tftpState | TFTP state machine tracker variable
smUpload | This is variable smUpload.
uploadChunkDescriptor | This is variable uploadChunkDescriptor.
uploadChunkDescriptorForRetransmit | This is variable uploadChunkDescriptorForRetransmit.
vUploadFilename | This is variable vUploadFilename.
vUploadRemoteHost | TFTPUploadRAMFileToHost(), TFTPUploadFragmentedRAMFileToHost() and TFTPGetUploadStatus() functions require the DNS client module to be enabled for them to work. The RAM and ROM resources for these functions can be preserved if the DNS client module isn't enabled.
wUploadChunkOffset | This is variable wUploadChunkOffset.
wUploadChunkOffsetForRetransmit | This is variable wUploadChunkOffsetForRetransmit.
Stack API > TFTP > Internal Members


MutExVar Variable

Contents | Index | Home
Previous | Up | Next
MutExVar Variable
C
union {
  struct {
    NODE_INFO _hostInfo;
  } group1;
  struct {
    WORD_VAL _tftpBlockNumber;
    WORD_VAL _tftpDuplicateBlock;
    WORD_VAL _tftpBlockLength;
  } group2;
} MutExVar;
Description

Mutually Exclusive variable groups to conserve RAM.

Stack API > TFTP > Internal Members > MutExVar Variable


TFTP_BLOCK_SIZE Macro

Contents | Index | Home
Previous | Up | Next
TFTP_BLOCK_SIZE Macro
C
#define TFTP_BLOCK_SIZE (0x200L)
Description

The size of a TFTP block - 512 bytes

Stack API > TFTP > Internal Members > TFTP_BLOCK_SIZE Macro


TFTP_BLOCK_SIZE_MSB Macro

Contents | Index | Home
Previous | Up | Next
TFTP_BLOCK_SIZE_MSB Macro
C
#define TFTP_BLOCK_SIZE_MSB (0x02u)
Description

The MSB of the TFTP_BLOCK_SIZE

Stack API > TFTP > Internal Members > TFTP_BLOCK_SIZE_MSB Macro


TFTP_CLIENT_PORT Macro

Contents | Index | Home
Previous | Up | Next
TFTP_CLIENT_PORT Macro
C
#define TFTP_CLIENT_PORT 65352L
Description

The TFTP Client port - a unique port on this device

Stack API > TFTP > Internal Members > TFTP_CLIENT_PORT Macro


TFTP_OPCODE Enumeration

Contents | Index | Home
Previous | Up | Next
TFTP_OPCODE Enumeration
C
typedef enum {
  TFTP_OPCODE_RRQ = 1,
  TFTP_OPCODE_WRQ,
  TFTP_OPCODE_DATA,
  TFTP_OPCODE_ACK,
  TFTP_OPCODE_ERROR
} TFTP_OPCODE;
Description

Enumeration of TFTP opcodes

Members
Members | Description
TFTP_OPCODE_RRQ = 1 | Get
TFTP_OPCODE_WRQ | Put
TFTP_OPCODE_DATA | Actual data
TFTP_OPCODE_ACK | Ack for Get/Put
TFTP_OPCODE_ERROR | Error
Stack API > TFTP > Internal Members > TFTP_OPCODE Enumeration


TFTP_SERVER_PORT Macro

Contents | Index | Home
Previous | Up | Next
TFTP_SERVER_PORT Macro
C
#define TFTP_SERVER_PORT (69L)
Description

The TFTP Server Port

Stack API > TFTP > Internal Members > TFTP_SERVER_PORT Macro


TFTP_STATE Enumeration

Contents | Index | Home
Previous | Up | Next
TFTP_STATE Enumeration
C
typedef enum {
  SM_TFTP_WAIT = 0,
  SM_TFTP_READY,
  SM_TFTP_WAIT_FOR_DATA,
  SM_TFTP_WAIT_FOR_ACK,
  SM_TFTP_DUPLICATE_ACK,
  SM_TFTP_SEND_ACK,
  SM_TFTP_SEND_LAST_ACK
} TFTP_STATE;
Description

The TFTP state machine

Stack API > TFTP > Internal Members > TFTP_STATE Enumeration


_tftpError Variable

Contents | Index | Home
Previous | Up | Next
_tftpError Variable
C
WORD _tftpError;
Description

Variable to preserve error condition causes for later transmission

Stack API > TFTP > Internal Members > _tftpError Variable


_tftpFlags Variable

Contents | Index | Home
Previous | Up | Next
_tftpFlags Variable
C
union {
  struct {
    unsigned int bIsFlushed : 1;
    unsigned int bIsAcked : 1;
    unsigned int bIsClosed : 1;
    unsigned int bIsClosing : 1;
    unsigned int bIsReading : 1;
  } bits;
  BYTE Val;
} _tftpFlags;
Description

TFTP status flags

Stack API > TFTP > Internal Members > _tftpFlags Variable


_tftpRetries Variable

Contents | Index | Home
Previous | Up | Next
_tftpRetries Variable
C
BYTE _tftpRetries;
Description

Tracker variable for the number of TFTP retries

Stack API > TFTP > Internal Members > _tftpRetries Variable


_TFTPSendAck Function

Contents | Index | Home
Previous | Up | Next
_TFTPSendAck Function
C
static void _TFTPSendAck(
    WORD_VAL blockNumber
);
Description

Private helper function

Stack API > TFTP > Internal Members > _TFTPSendAck Function


_TFTPSendFileName Function

Contents | Index | Home
Previous | Up | Next
_TFTPSendFileName Function
C
static void _TFTPSendFileName(
    TFTP_OPCODE command,
    BYTE * fileName
);
Description

Private helper function

Stack API > TFTP > Internal Members > _TFTPSendFileName Function


_TFTPSendROMFileName Function

Contents | Index | Home
Previous | Up | Next
_TFTPSendROMFileName Function
C
static void _TFTPSendROMFileName(
    TFTP_OPCODE opcode,
    ROM BYTE * fileName
);
Description

PIC18 ROM variable argument implementation of _TFTPSendFileName

Stack API > TFTP > Internal Members > _TFTPSendROMFileName Function


_tftpSocket Variable

Contents | Index | Home
Previous | Up | Next
_tftpSocket Variable
C
UDP_SOCKET _tftpSocket;
Description

TFTP Socket for TFTP server link

Stack API > TFTP > Internal Members > _tftpSocket Variable


_tftpStartTick Variable

Contents | Index | Home
Previous | Up | Next
_tftpStartTick Variable
C
DWORD _tftpStartTick;
Description

Timing variable used to detect timeout conditions

Stack API > TFTP > Internal Members > _tftpStartTick Variable


_tftpState Variable

Contents | Index | Home
Previous | Up | Next
_tftpState Variable
C
TFTP_STATE _tftpState;
Description

TFTP state machine tracker variable

Stack API > TFTP > Internal Members > _tftpState Variable


smUpload Variable

Contents | Index | Home
Previous | Up | Next
smUpload Variable
C
CHAR smUpload = TFTP_UPLOAD_COMPLETE;
Description

This is variable smUpload.

Stack API > TFTP > Internal Members > smUpload Variable


uploadChunkDescriptor Variable

Contents | Index | Home
Previous | Up | Next
uploadChunkDescriptor Variable
C
TFTP_CHUNK_DESCRIPTOR * uploadChunkDescriptor;
Description

This is variable uploadChunkDescriptor.

Stack API > TFTP > Internal Members > uploadChunkDescriptor Variable


uploadChunkDescriptorForRetransmit Variable

Contents | Index | Home
Previous | Up | Next
uploadChunkDescriptorForRetransmit Variable
C
TFTP_CHUNK_DESCRIPTOR * uploadChunkDescriptorForRetransmit;
Description

This is variable uploadChunkDescriptorForRetransmit.

Stack API > TFTP > Internal Members > uploadChunkDescriptorForRetransmit Variable


vUploadFilename Variable

Contents | Index | Home
Previous | Up | Next
vUploadFilename Variable
C
ROM BYTE * vUploadFilename;
Description

This is variable vUploadFilename.

Stack API > TFTP > Internal Members > vUploadFilename Variable


vUploadRemoteHost Variable

Contents | Index | Home
Previous | Up | Next
vUploadRemoteHost Variable
C
ROM BYTE * vUploadRemoteHost;
Description

TFTPUploadRAMFileToHost(), TFTPUploadFragmentedRAMFileToHost() and TFTPGetUploadStatus() functions require the DNS client module to be enabled for them to work. The RAM and ROM resources for these functions can be preserved if the DNS client module isn't enabled.

Stack API > TFTP > Internal Members > vUploadRemoteHost Variable


wUploadChunkOffset Variable

Contents | Index | Home
Previous | Up | Next
wUploadChunkOffset Variable
C
WORD wUploadChunkOffset;
Description

This is variable wUploadChunkOffset.

Stack API > TFTP > Internal Members > wUploadChunkOffset Variable


wUploadChunkOffsetForRetransmit Variable

Contents | Index | Home
Previous | Up | Next
wUploadChunkOffsetForRetransmit Variable
C
WORD wUploadChunkOffsetForRetransmit;
Description

This is variable wUploadChunkOffsetForRetransmit.

Stack API > TFTP > Internal Members > wUploadChunkOffsetForRetransmit Variable


Tick Module

Contents | Index | Home
Previous | Up | Next
Tick Module

The Tick module provides accurate time-keeping capabilities based on the hardware clock. By default, it uses Timer 0 on 8-bit parts and Timer 1 on 16- and 32-bit families. The module is interrupt driven, which makes the timing stable and accurate. As such, it is also suitable for a real-time clock.

The Tick module exists to assist with the implementation of non-blocking delays and timeouts. Rather than using a loop to count to a specific number, use the Tick module and compare a previous time with the current time. In this fashion applications can return its unused cycles to the stack during long delays, which increases the overall efficiency of the system.

Tick works best in conjunction with a state machine. In general, call TickGet and store the result. Return to the main stack application, and on future calls compare the current Tick value to the stored one. The constants TICK_SECOND, TICK_MINUTE, and TICK_HOUR can be used to compare against logical time increments.

The following example implements a delay of 0.5 seconds using the Tick module:

Copy Code
TICK startTime;

// ...state machine and other states

case SM_SET_DELAY:
    startTime = TickGet();
    sm = SM_DELAY_WAIT;
    return;

case SM_DELAY_WAIT:
    if((LONG)(TickGet() - startTime) < TICK_SECOND/2)
        return;

case SM_DELAY_DONE:
    // This state is entered only after 0.5 second elapses.

Ticks are stored internally as 48-bit integers. Using the various TickGet, TickGetDiv256, and TickGetDiv64K functions the Tick is suitable for measuring time increments from a few microseconds to a few years.

If absolute timestamps are required, the SNTP Client module may be more appropriate.

Topics
Name | Description
Tick Public Members | Functions and variables accessible by the stack application
Tick Stack Functions | Functions and variables intended to be accessed only by the stack
Tick Internal Members | Functions and variables internal to the Tick module
Stack API > Tick


Tick Public Members

Contents | Index | Home
Previous | Up | Next
Tick Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
TickConvertToMilliseconds | Converts a Tick value or difference to milliseconds.
TickGet | Obtains the current Tick value.
TickGetDiv256 | Obtains the current Tick value divided by 256.
TickGetDiv64K | Obtains the current Tick value divided by 64K.
Macros
Name | Description
TICK_HOUR | Represents one hour in Ticks
TICK_MINUTE | Represents one minute in Ticks
TICK_SECOND | Represents one second in Ticks
Module

Tick Module

Types
Name | Description
TICK | All TICKS are stored as 32-bit unsigned integers. This is deprecated since it conflicts with other TICK definitions used in other Microchip software libraries and therefore poses a merge and maintence problem. Instead of using the TICK data type, just use the base DWORD data type instead.
Stack API > Tick > Public Members


TICK Type

Contents | Index | Home
Previous | Up | Next
TICK Type
C
typedef DWORD TICK;
Description

All TICKS are stored as 32-bit unsigned integers. This is deprecated since it conflicts with other TICK definitions used in other Microchip software libraries and therefore poses a merge and maintence problem. Instead of using the TICK data type, just use the base DWORD data type instead.

Stack API > Tick > Public Members > TICK Type


TICK_HOUR Macro

Contents | Index | Home
Previous | Up | Next
TICK_HOUR Macro
C
#define TICK_HOUR ((QWORD)TICKS_PER_SECOND*3600ull)
Description

Represents one hour in Ticks

Stack API > Tick > Public Members > TICK_HOUR Macro


TICK_MINUTE Macro

Contents | Index | Home
Previous | Up | Next
TICK_MINUTE Macro
C
#define TICK_MINUTE ((QWORD)TICKS_PER_SECOND*60ull)
Description

Represents one minute in Ticks

Stack API > Tick > Public Members > TICK_MINUTE Macro


TICK_SECOND Macro

Contents | Index | Home
Previous | Up | Next
TICK_SECOND Macro
C
#define TICK_SECOND ((QWORD)TICKS_PER_SECOND)
Description

Represents one second in Ticks

Stack API > Tick > Public Members > TICK_SECOND Macro


TickConvertToMilliseconds Function

Contents | Index | Home
Previous | Up | Next
TickConvertToMilliseconds Function
C
DWORD TickConvertToMilliseconds(
    DWORD dwTickValue
);
Description

This function converts a Tick value or difference to milliseconds. For example, TickConvertToMilliseconds(32768) returns 1000 when a 32.768kHz clock with no prescaler drives the Tick module interrupt.

Preconditions

None

Parameters
Parameters | Description
dwTickValue | Value to convert to milliseconds
Returns

Input value expressed in milliseconds.

Remarks

This function performs division on DWORDs, which is slow. Avoid using it unless you absolutely must (such as displaying data to a user). For timeout comparisons, compare the current value to a multiple or fraction of TICK_SECOND, which will be calculated only once at compile time.

Stack API > Tick > Public Members > TickConvertToMilliseconds Function


TickGet Function

Contents | Index | Home
Previous | Up | Next
TickGet Function
C
DWORD TickGet();
Description

This function retrieves the current Tick value, allowing timing and measurement code to be written in a non-blocking fashion. This function retrieves the least significant 32 bits of the internal tick counter, and is useful for measuring time increments ranging from a few microseconds to a few hours. Use TickGetDiv256 or TickGetDiv64K for longer periods of time.

Preconditions

None

Returns

Lower 32 bits of the current Tick value.

Stack API > Tick > Public Members > TickGet Function


TickGetDiv256 Function

Contents | Index | Home
Previous | Up | Next
TickGetDiv256 Function
C
DWORD TickGetDiv256();
Description

This function retrieves the current Tick value, allowing timing and measurement code to be written in a non-blocking fashion. This function retrieves the middle 32 bits of the internal tick counter, and is useful for measuring time increments ranging from a few minutes to a few weeks. Use TickGet for shorter periods or TickGetDiv64K for longer ones.

Preconditions

None

Returns

Middle 32 bits of the current Tick value.

Stack API > Tick > Public Members > TickGetDiv256 Function


TickGetDiv64K Function

Contents | Index | Home
Previous | Up | Next
TickGetDiv64K Function
C
DWORD TickGetDiv64K();
Description

This function retrieves the current Tick value, allowing timing and measurement code to be written in a non-blocking fashion. This function retrieves the most significant 32 bits of the internal tick counter, and is useful for measuring time increments ranging from a few days to a few years, or for absolute time measurements. Use TickGet or TickGetDiv256 for shorter periods of time.

Preconditions

None

Returns

Upper 32 bits of the current Tick value.

Stack API > Tick > Public Members > TickGetDiv64K Function


Tick Stack Functions

Contents | Index | Home
Previous | Up | Next
Tick Stack Functions

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
TickInit | Initializes the Tick manager module.
TickUpdate | Updates the tick value when an interrupt occurs.
Module

Tick Module

Stack API > Tick > Stack Functions


TickInit Function

Contents | Index | Home
Previous | Up | Next
TickInit Function
C
void TickInit();
Description

Configures the Tick module and any necessary hardware resources.

Preconditions

None

Returns

None

Remarks

This function is called only one during lifetime of the application.

Stack API > Tick > Stack Functions > TickInit Function


TickUpdate Function

Contents | Index | Home
Previous | Up | Next
TickUpdate Function
C
void TickUpdate();
Description

Updates the tick value when an interrupt occurs.

Preconditions

None

Returns

None

Stack API > Tick > Stack Functions > TickUpdate Function


Tick Internal Members

Contents | Index | Home
Previous | Up | Next
Tick Internal Members

The following functions and variables are designated as internal to the Tick module.

Functions
Name | Description
GetTickCopy | Reads the tick value.
Macros
Name | Description
TICKS_PER_SECOND | Internal core clock drives timer with 1:256 prescaler #define TICKS_PER_SECOND (32768ul) // 32kHz crystal drives timer with no scalar
Module

Tick Module

Variables
Name | Description
dwInternalTicks | Internal counter to store Ticks. This variable is incremented in an ISR and therefore must be marked volatile to prevent the compiler optimizer from reordering code to use this value in the main context while interrupts are disabled.
vTickReading | 6-byte value to store Ticks. Allows for use over longer periods of time.
Stack API > Tick > Internal Members


dwInternalTicks Variable

Contents | Index | Home
Previous | Up | Next
dwInternalTicks Variable
C
volatile DWORD dwInternalTicks = 0;
Description

Internal counter to store Ticks. This variable is incremented in an ISR and therefore must be marked volatile to prevent the compiler optimizer from reordering code to use this value in the main context while interrupts are disabled.

Stack API > Tick > Internal Members > dwInternalTicks Variable


GetTickCopy Function

Contents | Index | Home
Previous | Up | Next
GetTickCopy Function
C
static void GetTickCopy();
Description

This function performs an interrupt-safe and synchronized read of the 48-bit Tick value.

Preconditions

None

Returns

None

Stack API > Tick > Internal Members > GetTickCopy Function


TICKS_PER_SECOND Macro

Contents | Index | Home
Previous | Up | Next
TICKS_PER_SECOND Macro
C
#define TICKS_PER_SECOND ((GetPeripheralClock()+128ull)/256ull)    // Internal core clock drives timer with 1:256 prescaler
Description

Internal core clock drives timer with 1:256 prescaler #define TICKS_PER_SECOND (32768ul) // 32kHz crystal drives timer with no scalar

Stack API > Tick > Internal Members > TICKS_PER_SECOND Macro


vTickReading Variable

Contents | Index | Home
Previous | Up | Next
vTickReading Variable
C
BYTE vTickReading[6];
Description

6-byte value to store Ticks. Allows for use over longer periods of time.

Stack API > Tick > Internal Members > vTickReading Variable


UDP

Contents | Index | Home
Previous | Up | Next
UDP
Types

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.

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.

The UDP flow diagram below provides an overview for the use of the UDP module:

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.

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 UDPPut family of functions to write data to the socket. Once all data has been written, call UDPFlush 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 UDPPut but before calling UDPFlush, the data may be lost or the module may behave unpredictably.

To check for received segments, call UDPIsGetReady. If the return value is non-zero, your application must consume the segment by reading data with the UDPGet family. Once all data has been read, return to the main stack loop to wait for an additional segment. UDP segments are only stored for one iteration of the cooperative multi-tasking loop, so your application must complete its processing on a segment or copy it elsewhere before returning. Note that this behavior differs from TCP, which buffers incoming data through multiple stack cycles.

When a socket is no longer needed, call UDPClose to release it back to the pool for future use.

Topics
Name | Description
UDP Public Members | Functions and variables accessible by the stack application
UDP Stack Members | Functions and variables intended to be accessed only by the stack
UDP Internal Members | Functions and variables internal to the UDP module
Types | The following table lists types in this documentation.
Types
Name | Description
UDP_STATE | UDP States
Stack API > UDP


UDP Public Members

Contents | Index | Home
Previous | Up | Next
UDP Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
UDPOpenEx | Opens a UDP socket for a client.
UDPClose | Closes a UDP socket and frees the handle.
UDPDiscard | Discards any remaining RX data from a UDP socket.
UDPFlush | Transmits all pending data in a UDP socket.
UDPGet | Reads a byte from the currently active socket.
UDPGetArray | Reads an array of bytes from the currently active socket.
UDPIsGetReady | Determines how many bytes can be read from the UDP socket.
UDPIsPutReady | Determines how many bytes can be written to the UDP socket.
UDPPut | Writes a byte to the currently active socket.
UDPPutArray | Writes an array of bytes to the currently active socket.
UDPPutROMArray | Writes an array of bytes from ROM to the currently active socket.
UDPPutROMString | Writes null-terminated string from ROM to the currently active socket.
UDPPutString | Writes null-terminated string to the currently active socket.
UDPSetRxBuffer | Moves the pointer within the RX buffer.
UDPSetTxBuffer | Moves the pointer within the TX buffer.
UDPIsOpened | Determines if a socket has an established connection.
Macros
Name | Description
INVALID_UDP_PORT | Indicates a UDP port that is not valid
INVALID_UDP_SOCKET | Indicates a UDP socket that is not valid
UDPOpen | Macro of the legacy version of UDPOpen.
UDP_OPEN_IP_ADDRESS | Create a client socket and use dwRemoteHost as a literal IP address.
UDP_OPEN_NODE_INFO | Create a client socket and use dwRemoteHost as a pointer to a NODE_INFO structure containing the exact remote IP address and MAC address to use.
UDP_OPEN_RAM_HOST | Emit an undeclared identifier diagnostic if code tries to use UDP_OPEN_RAM_HOST while the DNS client module is not enabled.
UDP_OPEN_ROM_HOST | Emit an undeclared identifier diagnostic if code tries to use UDP_OPEN_ROM_HOST while the DNS client module is not enabled.
UDP_OPEN_SERVER | Create a server socket and ignore dwRemoteHost.
Module

UDP

Types
Name | Description
UDP_SOCKET | Provides a handle to a UDP Socket
Stack API > UDP > Public Members


INVALID_UDP_PORT Macro

Contents | Index | Home
Previous | Up | Next
INVALID_UDP_PORT Macro
C
#define INVALID_UDP_PORT (0ul)        // Indicates a UDP port that is not valid
Description

Indicates a UDP port that is not valid

Stack API > UDP > Public Members > INVALID_UDP_PORT Macro


INVALID_UDP_SOCKET Macro

Contents | Index | Home
Previous | Up | Next
INVALID_UDP_SOCKET Macro
C
#define INVALID_UDP_SOCKET (0xffu)        // Indicates a UDP socket that is not valid
Description

Indicates a UDP socket that is not valid

Stack API > UDP > Public Members > INVALID_UDP_SOCKET Macro


UDP_SOCKET Type

Contents | Index | Home
Previous | Up | Next
UDP_SOCKET Type
C
typedef BYTE UDP_SOCKET;
Description

Provides a handle to a UDP Socket

Stack API > UDP > Public Members > UDP_SOCKET Type


UDPOpenEx Function

Contents | Index | Home
Previous | Up | Next
UDPOpenEx Function
C
UDP_SOCKET UDPOpenEx(
    DWORD remoteHost,
    BYTE remoteHostType,
    UDP_PORT localPort,
    UDP_PORT remotePort
);
Description

Provides a unified method for opening UDP sockets. This function can open both client and server sockets. For client sockets, it can accept a host name string to query in DNS, an IP address as a string, an IP address in binary form, or a previously resolved NODE_INFO structure containing the remote IP address and associated MAC address. When a host name or IP address only is provided, UDP module will internally perform the necessary DNSResolve and/or ARP resolution steps before reporting that the UDP socket is connected (via a call to UDPISOpen returning TRUE). Server sockets ignore this destination parameter and listen only on the indicated port. Sockets are statically allocated on boot, but can be claimed with this function and freed using UDPClose .

Preconditions

UDPInit should be called.

Parameters
Parameters
Description
remoteHost
Pointer to remote node info (MAC and IP address) for this connection. If this is a server socket (receives the first packet) or the destination is the broadcast address, then this parameter should be NULL. For client sockets only. Provide a pointer to a null-terminated string of the remote host name (ex:"www.microchip.com" or "192.168.1.123"), a literal destination IP address (ex: 0x7B01A8C0 or an IP_ADDR data type), or a pointer to a NODE_INFO structure with the remote IP address and remote node or gateway MAC address specified, If a string is provided.
remoteHostType
Any one of the following flags to identify the meaning of the remoteHost parameter:

  • UDP_OPEN_SERVER = Open a server socket and ignore the remoteHost parameter. (e.g. - SNMP agent, DHCP server, Announce)
  • UDP_OPEN_IP_ADDRESS = Open a client socket and connect it to a remote IP address. Ex: 0x7B01A8C0 for 192.168.1.123 (DWORD type). Note that the byte ordering is big endian.
  • UDP_OPEN_NODE_INFO = Open a client socket and connect it to a remote IP and MAC addresses pair stored in a NODE_INFO structure.
  • UDP_OPEN_RAM_HOST = Open a client socket and connect it to a remote host who's name is stored as a null terminated string in a RAM array. Ex:"www.microchip.com" or "192.168.0.123"
  • UDP_OPEN_ROM_HOST = Open a client socket and connect it to a remote host who's name is stored as a null terminated string in a literal string or ROM array. Ex: "www.microchip.com" or "192.168.0.123"

localPort
UDP port number to listen on. If 0, stack will dynamically assign a unique port number to use.
remotePort
For client sockets, the remote port number.
Return Values
Return Values | Description
Success | A UDP socket handle that can be used for subsequent UDP API calls.
Failure | INVALID_UDP_SOCKET. This function fails when no more UDP socket handles are available. Increase MAX_UDP_SOCKETS to make more sockets available.
Remarks

When finished using the UDP socket handle, call the UDPClose() function to free the socket and delete the handle.

Stack API > UDP > Public Members > UDPOpenEx Function


UDPOpen Macro

Contents | Index | Home
Previous | Up | Next
UDPOpen Macro
C
#define UDPOpen(localPort,remoteNode,remotePort) UDPOpenEx((DWORD)remoteNode,UDP_OPEN_NODE_INFO,localPort,remotePort)
Description

UDPOpen is a macro replacement of the legacy implementation of UDPOpen. Creates a UDP socket handle for transmiting or receiving UDP packets. Call this function to obtain a handle required by other UDP function.

Preconditions

UDPInit() must have been previously called.

Parameters
Parameters | Description
localPort | UDP port number to listen on. If 0, stack will dynamically assign a unique port number to use.
remoteNode | Pointer to remote node info (MAC and IP address) for this connection. If this is a server socket (receives the first packet) or the destination is the broadcast address, then this parameter should be NULL.
remotePort | For client sockets, the remote port number.
Return Values
Return Values | Description
Success | A UDP socket handle that can be used for subsequent UDP API calls.
Failure | INVALID_UDP_SOCKET. This function fails when no more UDP socket handles are available. Increase MAX_UDP_SOCKETS to make more sockets available.
Remarks

When finished using the UDP socket handle, call the UDPClose() function to free the socket and delete the handle.

Stack API > UDP > Public Members > UDPOpen Macro


UDPClose Function

Contents | Index | Home
Previous | Up | Next
UDPClose Function
C
void UDPClose(
    UDP_SOCKET s
);
Description

UDP_SOCKET UDPOpen(UDP_PORT localPort, NODE_INFO *remoteNode, UDP_PORT remotePort);

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

UDPInit() must have been previously called.

Parameters
Parameters | Description
s | The socket handle to be released. If an illegal handle value is provided, the function safely does nothing.
Returns

None

Remarks

This function does not affect the previously designated active socket.

Stack API > UDP > Public Members > UDPClose Function


UDPDiscard Function

Contents | Index | Home
Previous | Up | Next
UDPDiscard Function
C
void UDPDiscard();
Description

This function discards any remaining received data in the currently active UDP socket.

Preconditions

UDPIsGetReady() was previously called to select the currently active socket.

Returns

None

Remarks

It is safe to call this function more than is necessary. If no data is available, this function does nothing.

Stack API > UDP > Public Members > UDPDiscard Function


UDPFlush Function

Contents | Index | Home
Previous | Up | Next
UDPFlush Function
C
void UDPFlush();
Description

This function builds a UDP packet with the pending TX data and marks it for transmission over the network interface. Since UDP is a frame-based protocol, this function must be called before returning to the main stack loop whenever any data is written.

Preconditions

UDPIsPutReady() was previously called to specify the current socket, and data has been written to the socket using the UDPPut family of functions.

Returns

None

Remarks

Note that unlike TCPFlush, UDPFlush must be called before returning to the main stack loop. There is no auto transmit for UDP segments.

Stack API > UDP > Public Members > UDPFlush Function


UDPGet Function

Contents | Index | Home
Previous | Up | Next
UDPGet Function
C
BOOL UDPGet(
    BYTE * v
);
Description

This function reads a single byte from the currently active UDP socket, while decrementing the remaining buffer length. UDPIsGetReady should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsGetReady() was previously called to specify the current socket.

Parameters
Parameters | Description
v | The buffer to receive the data being read.
Return Values
Return Values | Description
TRUE | A byte was successfully read
FALSE | No data remained in the read buffer
Stack API > UDP > Public Members > UDPGet Function


UDPGetArray Function

Contents | Index | Home
Previous | Up | Next
UDPGetArray Function
C
WORD UDPGetArray(
    BYTE * cData,
    WORD wDataLen
);
Description

This function reads an array of bytes from the currently active UDP socket, while decrementing the remaining bytes available. UDPIsGetReady should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsGetReady() was previously called to specify the current socket.

Parameters
Parameters | Description
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 UDPSetRxBuffer() 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.

Stack API > UDP > Public Members > UDPGetArray Function


UDPIsGetReady Function

Contents | Index | Home
Previous | Up | Next
UDPIsGetReady Function
C
WORD UDPIsGetReady(
    UDP_SOCKET s
);
Description

This function determines if bytes can be read from the specified UDP socket. It also prepares the UDP module for reading by setting the indicated socket as the currently active connection.

Preconditions

UDPInit() must have been previously called.

Parameters
Parameters | Description
s | The socket to be made active (which has already been opened or is listening)
Returns

The number of bytes that can be read from this socket.

Stack API > UDP > Public Members > UDPIsGetReady Function


UDPIsPutReady Function

Contents | Index | Home
Previous | Up | Next
UDPIsPutReady Function
C
WORD UDPIsPutReady(
    UDP_SOCKET s
);
Description

This function determines if bytes can be written to the specified UDP socket. It also prepares the UDP module for writing by setting the indicated socket as the currently active connection.

Preconditions

UDPInit() must have been previously called.

Parameters
Parameters | Description
s | The socket to be made active
Returns

The number of bytes that can be written to this socket.

Stack API > UDP > Public Members > UDPIsPutReady Function


UDPPut Function

Contents | Index | Home
Previous | Up | Next
UDPPut Function
C
BOOL UDPPut(
    BYTE v
);
Description

This function writes a single byte to the currently active UDP socket, while incrementing the buffer length. UDPIsPutReady should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsPutReady() was previously called to specify the current socket.

Parameters
Parameters | Description
v | The byte to be loaded into the transmit buffer.
Return Values
Return Values | Description
TRUE | The byte was successfully written to the socket.
FALSE | The transmit buffer is already full and so the write failed.
Stack API > UDP > Public Members > UDPPut Function


UDPPutArray Function

Contents | Index | Home
Previous | Up | Next
UDPPutArray Function
C
WORD UDPPutArray(
    BYTE * cData,
    WORD wDataLen
);
Description

This function writes an array of bytes to the currently active UDP socket, while incrementing the buffer length. UDPIsPutReady should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsPutReady() was previously called to specify the current 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 full and the input was truncated.

Stack API > UDP > Public Members > UDPPutArray Function


UDPPutROMArray Function

Contents | Index | Home
Previous | Up | Next
UDPPutROMArray Function
C
WORD UDPPutROMArray(
    ROM BYTE * cData,
    WORD wDataLen
);
Description

ROM function variants for PIC18

This function writes an array of bytes from ROM to the currently active UDP socket, while incrementing the buffer length. UDPIsPutReady should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsPutReady() was previously called to specify the current 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 full and the input was truncated.

Remarks

This function is aliased to UDPPutArray on non-PIC18 platforms.

Stack API > UDP > Public Members > UDPPutROMArray Function


UDPPutROMString Function

Contents | Index | Home
Previous | Up | Next
UDPPutROMString Function
C
ROM BYTE* UDPPutROMString(
    ROM BYTE * strData
);
Description

This function writes a null-terminated string from ROM to the currently active UDP socket, while incrementing the buffer length. UDPIsPutReady should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsPutReady() was previously called to specify the current socket.

Parameters
Parameters | Description
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 UDPPutArray functions. If this pointer does not dereference to a NULL byte, then the buffer became full and the input data was truncated.

Remarks

This function is aliased to UDPPutString on non-PIC18 platforms.

Stack API > UDP > Public Members > UDPPutROMString Function


UDPPutString Function

Contents | Index | Home
Previous | Up | Next
UDPPutString Function
C
BYTE* UDPPutString(
    BYTE * strData
);
Description

This function writes a null-terminated string to the currently active UDP socket, while incrementing the buffer length. UDPIsPutReady should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsPutReady() was previously called to specify the current socket.

Parameters
Parameters | Description
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 UDPPutArray functions. If this pointer does not dereference to a NULL byte, then the buffer became full and the input data was truncated.

Stack API > UDP > Public Members > UDPPutString Function


UDPSetRxBuffer Function

Contents | Index | Home
Previous | Up | Next
UDPSetRxBuffer Function
C
void UDPSetRxBuffer(
    WORD wOffset
);
Description

This function allows the read location within the RX buffer to be specified. Future calls to UDPGet and UDPGetArray will read data from the indicated location forward.

Preconditions

UDPInit() must have been previously called and a socket is currently active.

Parameters
Parameters | Description
wOffset | Offset from beginning of UDP packet data payload to place the read pointer.
Returns

None

Stack API > UDP > Public Members > UDPSetRxBuffer Function


UDPSetTxBuffer Function

Contents | Index | Home
Previous | Up | Next
UDPSetTxBuffer Function
C
void UDPSetTxBuffer(
    WORD wOffset
);
Description

This function allows the write location within the TX buffer to be specified. Future calls to UDPPut, UDPPutArray, UDPPutString, etc will write data from the indicated location.

Preconditions

UDPInit() must have been previously called and a socket is currently active.

Parameters
Parameters | Description
wOffset | Offset from beginning of UDP packet data payload to place the write pointer.
Returns

None

Stack API > UDP > Public Members > UDPSetTxBuffer Function


UDPIsOpened Function

Contents | Index | Home
Previous | Up | Next
UDPIsOpened Function
C
BOOL UDPIsOpened(
    UDP_SOCKET socket
);
Description

This function determines if a socket has an established connection to a remote node . Call this function after calling UDPOpen to determine when the connection is set up and ready for use.

Preconditions

UDP is initialized.

Parameters
Parameters | Description
socket | 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

Stack API > UDP > Public Members > UDPIsOpened Function


UDP_OPEN_IP_ADDRESS Macro

Contents | Index | Home
Previous | Up | Next
UDP_OPEN_IP_ADDRESS Macro
C
#define UDP_OPEN_IP_ADDRESS 3u
Description

Create a client socket and use dwRemoteHost as a literal IP address.

Stack API > UDP > Public Members > UDP_OPEN_IP_ADDRESS Macro


UDP_OPEN_NODE_INFO Macro

Contents | Index | Home
Previous | Up | Next
UDP_OPEN_NODE_INFO Macro
C
#define UDP_OPEN_NODE_INFO 4u
Description

Create a client socket and use dwRemoteHost as a pointer to a NODE_INFO structure containing the exact remote IP address and MAC address to use.

Stack API > UDP > Public Members > UDP_OPEN_NODE_INFO Macro


UDP_OPEN_RAM_HOST Macro

Contents | Index | Home
Previous | Up | Next
UDP_OPEN_RAM_HOST Macro
C
#define UDP_OPEN_RAM_HOST You_need_to_enable_STACK_USE_DNS_to_use_UDP_OPEN_RAM_HOST
Description

Emit an undeclared identifier diagnostic if code tries to use UDP_OPEN_RAM_HOST while the DNS client module is not enabled.

Stack API > UDP > Public Members > UDP_OPEN_RAM_HOST Macro


UDP_OPEN_ROM_HOST Macro

Contents | Index | Home
Previous | Up | Next
UDP_OPEN_ROM_HOST Macro
C
#define UDP_OPEN_ROM_HOST You_need_to_enable_STACK_USE_DNS_to_use_UDP_OPEN_ROM_HOST
Description

Emit an undeclared identifier diagnostic if code tries to use UDP_OPEN_ROM_HOST while the DNS client module is not enabled.

Stack API > UDP > Public Members > UDP_OPEN_ROM_HOST Macro


UDP_OPEN_SERVER Macro

Contents | Index | Home
Previous | Up | Next
UDP_OPEN_SERVER Macro
C
#define UDP_OPEN_SERVER 0u
Description

Create a server socket and ignore dwRemoteHost.

Stack API > UDP > Public Members > UDP_OPEN_SERVER Macro


UDP Stack Members

Contents | Index | Home
Previous | Up | Next
UDP Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
UDPInit | Initializes the UDP module.
UDPProcess | Handles an incoming UDP segment.
UDPTask | Performs state management and housekeeping for UDP.
Module

UDP

Stack API > UDP > Stack Members


UDPInit Function

Contents | Index | Home
Previous | Up | Next
UDPInit Function
C
void UDPInit();
Description

Initializes the UDP module. This function initializes all the UDP sockets to the closed state.

Preconditions

None

Returns

None

Remarks

This function is called only one during lifetime of the application.

Stack API > UDP > Stack Members > UDPInit Function


UDPProcess Function

Contents | Index | Home
Previous | Up | Next
UDPProcess Function
C
BOOL UDPProcess(
    NODE_INFO * remoteNode,
    IP_ADDR * localIP,
    WORD len
);
Description

This function handles an incoming UDP segment to determine if it is acceptable and should be handed to one of the stack applications for processing.

Preconditions

UDPInit() has been called an a UDP segment is ready in the MAC buffer.

Parameters
Parameters | Description
remoteNode | The remote node that sent this segment.
localIP | The destination IP address for this segment.
len | Total length of the UDP segment.
Return Values
Return Values | Description
TRUE | A valid packet is waiting and the stack applications should be called to handle it.
FALSE | The packet was discarded.
Stack API > UDP > Stack Members > UDPProcess Function


UDPTask Function

Contents | Index | Home
Previous | Up | Next
UDPTask Function
C
void UDPTask();
Description

Performs state management and housekeeping for UDP. This is an internal function meant to be called by StackTask() (not a user API).

Preconditions

None

Remarks

UDPTask() is called once per StackTask() iteration to ensure that calls to UDPIsPutReady() always update the Ethernet Write pointer location between StackTask() iterations.

Stack API > UDP > Stack Members > UDPTask Function


UDP Internal Members

Contents | Index | Home
Previous | Up | Next
UDP Internal Members

The following functions and variables are designated as internal to the UDP module.

Functions
Name | Description
FindMatchingSocket | Matches an incoming UDP segment to a currently active socket.
Macros
Name | Description
LOCAL_UDP_PORT_END_NUMBER | Last port number for randomized local port number selection
LOCAL_UDP_PORT_START_NUMBER | First port number for randomized local port number selection
Module

UDP

Structures
Name | Description
UDP_HEADER | Stores the header of a UDP packet
UDP_SOCKET_INFO | Stores information about a current UDP socket
Types
Name | Description
UDP_PORT | Stores a UDP Port Number
Variables
Name | Description
activeUDPSocket | Indicates which UDP socket is currently active
LastPutSocket | Indicates the last socket to which data was written
SocketWithRxData | Indicates which socket has currently received data for this loop
UDPRxCount | Number of bytes read from this UDP segment
UDPSocketInfo | Stores an array of information pertaining to each UDP socket
UDPTxCount | Number of bytes written to this UDP segment
wGetOffset | Offset from beginning of payload from where data is to be read.
wPutOffset | Offset from beginning of payload where data is to be written.
Stack API > UDP > Internal Members


activeUDPSocket Variable

Contents | Index | Home
Previous | Up | Next
activeUDPSocket Variable
C
UDP_SOCKET activeUDPSocket;
Description

Indicates which UDP socket is currently active

Stack API > UDP > Internal Members > activeUDPSocket Variable


FindMatchingSocket Function

Contents | Index | Home
Previous | Up | Next
FindMatchingSocket Function
C
static UDP_SOCKET FindMatchingSocket(
    UDP_HEADER * h,
    NODE_INFO * remoteNode,
    IP_ADDR * localIP
);
Description

This function attempts to match an incoming UDP segment to a currently active socket for processing.

Preconditions

UDP segment header and IP header have both been retrieved.

Parameters
Parameters | Description
h | The UDP header that was received.
remoteNode | IP and MAC of the remote node that sent this segment.
localIP | IP address that this segment was destined for.
Returns

A UDP_SOCKET handle of a matching socket, or INVALID_UDP_SOCKET when no match could be made.

Stack API > UDP > Internal Members > FindMatchingSocket Function


LastPutSocket Variable

Contents | Index | Home
Previous | Up | Next
LastPutSocket Variable
C
UDP_SOCKET LastPutSocket = INVALID_UDP_SOCKET;
Description

Indicates the last socket to which data was written

Stack API > UDP > Internal Members > LastPutSocket Variable


LOCAL_UDP_PORT_END_NUMBER Macro

Contents | Index | Home
Previous | Up | Next
LOCAL_UDP_PORT_END_NUMBER Macro
C
#define LOCAL_UDP_PORT_END_NUMBER (8192u)
Description

Last port number for randomized local port number selection

Stack API > UDP > Internal Members > LOCAL_UDP_PORT_END_NUMBER Macro


LOCAL_UDP_PORT_START_NUMBER Macro

Contents | Index | Home
Previous | Up | Next
LOCAL_UDP_PORT_START_NUMBER Macro
C
#define LOCAL_UDP_PORT_START_NUMBER (4096u)
Description

First port number for randomized local port number selection

Stack API > UDP > Internal Members > LOCAL_UDP_PORT_START_NUMBER Macro


SocketWithRxData Variable

Contents | Index | Home
Previous | Up | Next
SocketWithRxData Variable
C
UDP_SOCKET SocketWithRxData = INVALID_UDP_SOCKET;
Description

Indicates which socket has currently received data for this loop

Stack API > UDP > Internal Members > SocketWithRxData Variable


UDP_HEADER Structure

Contents | Index | Home
Previous | Up | Next
UDP_HEADER Structure
C
typedef struct {
  UDP_PORT SourcePort;
  UDP_PORT DestinationPort;
  WORD Length;
  WORD Checksum;
} UDP_HEADER;
Description

Stores the header of a UDP packet

Members
Members | Description
UDP_PORT SourcePort; | Source UDP port
UDP_PORT DestinationPort; | Destination UDP port
WORD Length; | Length of data
WORD Checksum; | UDP checksum of the data
Stack API > UDP > Internal Members > UDP_HEADER Structure


UDP_PORT Type

Contents | Index | Home
Previous | Up | Next
UDP_PORT Type
C
typedef WORD UDP_PORT;
Description

Stores a UDP Port Number

Stack API > UDP > Internal Members > UDP_PORT Type


UDP_SOCKET_INFO Structure

Contents | Index | Home
Previous | Up | Next
UDP_SOCKET_INFO Structure
C
typedef struct {
  union {
    NODE_INFO remoteNode;
    DWORD remoteHost;
  } remote;
  UDP_PORT remotePort;
  UDP_PORT localPort;
  UDP_STATE smState;
  DWORD retryInterval;
  BYTE retryCount;
  struct {
    unsigned char bRemoteHostIsROM : 1;
  } flags;
  WORD eventTime;
} UDP_SOCKET_INFO;
Description

Stores information about a current UDP socket

Members
Members | Description
NODE_INFO remoteNode; | 10 bytes for MAC and IP address
DWORD remoteHost; | RAM or ROM pointer to a hostname string (ex: "www.microchip.com")
UDP_PORT remotePort; | Remote node's UDP port number
UDP_PORT localPort; | Local UDP port number, or INVALID_UDP_PORT when free
UDP_STATE smState; | State of this socket
unsigned char bRemoteHostIsROM : 1; | Remote host is stored in ROM
Stack API > UDP > Internal Members > UDP_SOCKET_INFO Structure


UDPRxCount Variable

Contents | Index | Home
Previous | Up | Next
UDPRxCount Variable
C
WORD UDPRxCount;
Description

Number of bytes read from this UDP segment

Stack API > UDP > Internal Members > UDPRxCount Variable


UDPSocketInfo Variable

Contents | Index | Home
Previous | Up | Next
UDPSocketInfo Variable
C
UDP_SOCKET_INFO UDPSocketInfo[MAX_UDP_SOCKETS];
Description

Stores an array of information pertaining to each UDP socket

Stack API > UDP > Internal Members > UDPSocketInfo Variable


UDPTxCount Variable

Contents | Index | Home
Previous | Up | Next
UDPTxCount Variable
C
WORD UDPTxCount;
Description

Number of bytes written to this UDP segment

Stack API > UDP > Internal Members > UDPTxCount Variable


wGetOffset Variable

Contents | Index | Home
Previous | Up | Next
wGetOffset Variable
C
WORD wGetOffset;
Description

Offset from beginning of payload from where data is to be read.

Stack API > UDP > Internal Members > wGetOffset Variable


wPutOffset Variable

Contents | Index | Home
Previous | Up | Next
wPutOffset Variable
C
WORD wPutOffset;
Description

Offset from beginning of payload where data is to be written.

Stack API > UDP > Internal Members > wPutOffset Variable


Types

Contents | Index | Home
Previous | Up | Next
Types
Enumerations
Name | Description
UDP_STATE | UDP States
Module

UDP

Stack API > UDP > Types


UDP_STATE Enumeration

Contents | Index | Home
Previous | Up | Next
UDP_STATE Enumeration
C
typedef enum {
  UDP_DNS_IS_RESOLVED,
  UDP_DNS_RESOLVE,
  UDP_GATEWAY_SEND_ARP,
  UDP_GATEWAY_GET_ARP,
  UDP_CLOSED,
  UDP_OPENED
} UDP_STATE;
Description

UDP States

Members
Members | Description
UDP_DNS_IS_RESOLVED | Special state for UDP client mode sockets
UDP_DNS_RESOLVE | Special state for UDP client mode sockets
UDP_GATEWAY_SEND_ARP | Special state for UDP client mode sockets
UDP_GATEWAY_GET_ARP | Special state for UDP client mode sockets
UDP_CLOSED | Socket is idle and unallocated
Stack API > UDP > Types > UDP_STATE Enumeration


Wi-Fi API

Contents | Index | Home
Previous | Next
Wi-Fi API

Unlike Ethernet, a WiFi application needs to initiate a connection to an access point or an ad hoc network) before data communications can commence. In order to initiate an connection there is a sequence of steps that should be followed.

1) A connection profile must be created (see WF_CPCreate()). The connection profile contains information directing the WiFi driver about the nature of the connection that will be established. The connection profile defines:

a. SSID (name of Access Point)

b. Security (open, WEP, WPA, etc.)

c. Network type (infrastructure or ad hoc).

The Connection Profile functions are used to create and define an connection profile. These functions all begin with WF_CP…

2) The connection algorithm must be defined, and applies to all connection profiles. For most applications the defaults will be sufficient. For example, the default connection algorithm channel list for scanning is 1, 6, and 11. However, if, in your application you know the Access Point will always be on channel 6 you could change this setting, thus making the scan process more efficient. Functions pertaining to the connection algorithm all begin with WF_CA…

3) Once a connection profile and the connection algorithm are customized for an application, the WF_CMConnect() function must be called to initiate the connection process.

4) After WF_Connect() is called the host application will be notified when the MRF24WB0M has succeeded (or failed) in establishing a connection via the event mechanism. The WF_Config.c file has a function, WF_ProcessEvent(), that is a template for processing MRF24WB0M events. In the WiFi demos it simply prints to the console (if the UART is enabled) that the event occurred. This file can be modified to suit the needs of an application – for example, an application could pend on a global flag that would be set in WF_ProcessEvent() when the connection succeeded. Please refer to WF_ProcessEvent for more information on WiFi event handling.

The MRF2WB0M demos (under the Demo App, WiFi Console, and WiFi EZ Config demo directories) contain a function, WF_Connect(), in MainDemo.c that executes the above steps and can be referred to as an example of how to initiate a WiFi connection. The WF_Config.h file has several compile-time constants that can be customized (e.g. MY_DEFAULT_SSID_NAME) as needed.

This help file book describes the host API to the MRF24WB0M on-chip connection manager which creates and maintains Wi-Fi connections. The API is divided into these major sections:

API Section | Description
Initialization | Functions to initialize the host API and MRF24WB0M
Connection Profile | Functions to create and maintain one or more connection profiles
Connection Algorithm | Functions to fine tune the connection algorithm
Connection Manager | Functions to start and stop an 802.11 connection
Scan | Functions to scan for wireless networks
Tx Power Control | Functions to control the MRF24WB0M Tx power
Power Save | Functions to save power consumption by the MRF24WB0M
Multicast | Functions to create multicast filters
Miscellaneous | Functions to set a custom MAC address, get device information, etc.
MRF24WB0M Events | Functions to handle events from the MRF24WB0M

SPI

The WF_Spi.c file contains functions that the Wi-Fi Driver will use to initialize, send, and receive SPI messages between the host CPU and the MRF24WB0M. To communicate with the MRF24WB0M, which is always an SPI slave, the host CPU SPI controller needs to be configured as follows:

  • Mode = 0
  • CPOL (clock polarity) = 0
  • CPHA (clock phase) = 0
  • Host CPU set as master
  • Clock idles high
  • 8-bit transfer length
  • Data changes on falling edge
  • Data sampled on rising edge

Below is a list of functions in WF_Spi.c that must be customized for the specific host CPU architecture:

Function | Description
WF_SpiInit() | Initializes the host CPU SPI controller for usage by the Wi-Fi driver. Called by the Wi-Fi driver during initialization.
WF_SpiTxRx() | Transmits and/or receives SPI data from the MRF24WB0M.
WF_SpiEnableChipSelect() | Set slave select line on MRF24WB0M low (start SPI transfer). If SPI bus is shared with any other devices then this function also needs to save the current SPI context and then configure the MRF24WB0M SPI context.
WF_SpiDisableChipSelect() | Set slave select line on MRF24WB0M high (end SPI transfer). If SPI bus is shared with any other devices then this function also needs to restore the SPI context (saved during WF_SpiEnableChipSelect()).

External Interrupt

The WF_Eint.c file contains functions that the Wi-Fi Driver will use to enable and disable the MRF24WB0M external interrupt as well as get interrupt status. The functions in this module need to be customized for the specific host CPU architecture.

The MRF24WB0M asserts its EXINT (external interrupt) line (active low) when specific events occur, such as a data message being received. Note that the host CPU has a choice to either configure the EXINT line to generate an actual interrupt, or, it can be polled. Below is a list of the Wi-Fi Driver functions within WF_Eint.c that must be customized for the specific Host CPU architecture.

Function | Description
WF_EintInit() | Configures the interrupt for use and leaves it in a disabled state. Will be called by the Wi-Fi driver during initialization. If polling the EXINT pin then this function won’t have any work to do except leave the interrupt in a logically disabled state.
WF_EintEnable() | Enables the MRF24WB0M external interrupt. If using real interrupts then enable the interrupt. If polling the EXINT pin then this function enables polling of the pin.
WF_EintDisable() | Disables the MRF24WB0M external interrupt. If using real interrupts then disable the interrupt. If polling the EXINT pin then this function disables polling of the pin.
WF_EintIsr() | This is the interrupt service routine invoked when the EXINT line goes low. It should perform any necessary housekeeping , such as clearing the interrupt. The interrupt must remain disabled until the Wi-Fi Driver calls WF_EintEnable(). The Wi-Fi driver function, WFEintHandler() must be called.
WF_EintIsDisabled() | Returns true if the external interrupt is disabled, else returns false.
WFEintHandler() | This function does not need to be customized – it is part of the Wi-Fi driver. However, it is added to this list because it must be called each time the MRF24WB0M interrupt service routine (ISR) occurs.
WF_Config

The WF_Config module (WF_Config.h/WF_Config.c) is used to control several aspects of the WiFi Driver behavior. Most of the customization of the Wi-Fi module is done from the context of this module.

Removal of Unused Driver Functions

In WF_Customize.h there is a block of defines that can be commented out to remove those sections of the Wi-Fi host driver that are not needed by the application. This allows the saving of code and data space.

#define
Controlling Functions
WF_USE_SCAN_FUNCTIONS
Scan API
WF_USE_TX_POWER_CONTROL_FUNCTIONS
Tx power control API
WF_USE_POWER_SAVE_FUNCTIONS
Power save API
WF_USE_MULTICAST_FUNCTIONS
Multicast API
WF_USE_INDIVIDUAL_SET_GETS
Affects all get and set functions, except the following:
WF_CPSetElements()
WF_CPGetElements()
WF_CASetElements()
WF_CAGetElements()
WF_USE_GROUP_SET_GETS
Affects the following functions:
WF_CPSetElements()
WF_CPGetElements()
WF_CASetElements()
WF_CAGetElements()
WF_DEBUG

This define enables the WF_ASSERT macro in the Wi-Fi driver. Customer code is free to use this macro. The WF_ASSERT macro can be compiled in or out via the WF_DEBUG define. See the comment above the WF_DEBUG define in WF_Customize.h for details.

WF_CONSOLE

The Wi-Fi driver has a UART console application built in that allows one to type in command lines and has them parsed. If this functionality is not needed than it can be compiled out by commenting out the WF_CONSOLE define.

WF_ProcessEvent()

This function is called by the Wi-Fi Driver when an event occurs that the host CPU needs to be notified of. There are several Wi-Fi connection related events that the application can choose whether to be notified or not. And, there are several events the application will always be notified of.

The function WF_ProcessEvent() can be customized to support desired handling of events.

Modules
Name | Description
Wi-Fi Connection Profile | Functions to setup, use, and teardown connection profiles
Wi-Fi Connection Algorithm | Functions to alter the behavior of the connection process
Wi-Fi Connection Manager | Functions to manage the connection process
Wi-Fi Scan | Functions to direct the MRF24WB0M to initiate a site survey
Wi-Fi Tx Power Control | API to control the Tx power of the MRF24WB0M
Wi-Fi Power Save | Functions to alter the power savings features of the MRF24WB0M
Wi-Fi Miscellaneous | Functions for controlling miscellaneous features of the MRF24WB0M
Topics
Name | Description
WF_ProcessEvent | Describes how to receive and act on events from the MRF24WB0M
Access Point Compatibility |
WiFi Tips and Tricks | Describes some basic tips for setting up and configuring a WiFi network.
Hot Topics | Lists some answers to some common WiFi questions.
Wi-Fi API


Wi-Fi Connection Profile

Contents | Index | Home
Previous | Up | Next
Wi-Fi Connection Profile

This section describes the API functions related to creating and using connection profiles. At least one connection profile must be created. The connection profile defines elements required by the MRF24WB0M to establish a connection to a Wi-Fi network.

Modifying Connection Profile after Connection is Established

A connection profile can be updated while it is being used for an active connection. However, the updates do not take effect until one of the following occurs:

• Connection is disabled and re-enabled by the host application

• Connection algorithm loses the connection, exhausts all retries, and then reloads the connection profile.

To ensure that connection profile updates take place at a known point in time it is recommended that the host application call WF_CMDisconnect(), update the connection profile, then call WF_CMConnect().

Module

Wi-Fi API

Topics
Name | Description
Connection Profile Public Members |
Connection Profile Internal Members |
Wi-Fi API > Wi-Fi Connection Profile


Connection Profile Public Members

Contents | Index | Home
Previous | Up | Next
Connection Profile Public Members
Functions
Name | Description
WF_CPCreate | Creates a Connection Profile on the MRF24WB0M.
WF_CPDelete | Deletes a Connection Profile on the MRF24WB0M.
WF_CPGetAdHocBehavior | Gets the desired Ad Hoc behavior
WF_CPGetBssid | Gets the BSSID for the specified Connection Profile ID.
WF_CPGetDefaultWepKeyIndex | Gets the value of the active WEP keys to use.
WF_CPGetElements | Reads the Connection Profile elements for the specified ID.
WF_CPGetIds | Retrieves the CP ID bit mask.
WF_CPGetNetworkType | Gets the network for the specified Connection Profile ID.
WF_CPGetSecurity | Gets the security for the specified Connection Profile.
WF_CPGetSsid | Gets the SSID for the specified Connection Profile ID.
WF_CPSetAdHocBehavior | Selects the desired Ad Hoc behavior
WF_CPSetBssid | Sets the BSSID for the specified Connection Profile ID.
WF_CPSetDefaultWepKeyIndex | Selects one of the 4 WEP keys to use.
WF_CPSetElements | Writes out data for a specific connection profile element.
WF_CPSetNetworkType | Sets the network for the specified Connection Profile ID.
WF_CPSetSecurity | Sets the security for the specified Connection Profile.
WF_CPSetSsid | Sets the SSID for the specified Connection Profile ID.
Module

Wi-Fi Connection Profile

Structures
Name | Description
WFCPElementsStruct | Connection profile elements structure
Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members


WF_CPCreate Function

Contents | Index | Home
Previous | Up | Next
WF_CPCreate Function
C
void WF_CPCreate(
    UINT8 * p_CpId
);
Description

Connection Profile Functions

Requests the MRF24WB0M to create a Connection Profile (CP), assign it an ID, and set all the elements to default values. The ID returned by this function is used in other connection profile functions. A maximum of 2 Connection Profiles can exist on the MRF24WB0M.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_CpId | Pointer to where Connection Profile ID will be written. If function fails, the CP ID will be set to 0xff.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPCreate Function


WF_CPDelete Function

Contents | Index | Home
Previous | Up | Next
WF_CPDelete Function
C
void WF_CPDelete(
    UINT8 CpId
);
Description

Deletes the specified Connection Profile. If the Connection Profile was in FLASH it will be erased from FLASH.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile to delete test case.
Returns

None.

Remarks

First release of this code will not support FLASH, only the two CP’s in memory.

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPDelete Function


WF_CPGetAdHocBehavior Function

Contents | Index | Home
Previous | Up | Next
WF_CPGetAdHocBehavior Function
C
void WF_CPGetAdHocBehavior(
    UINT8 CpId,
    UINT8 * p_adHocBehavior
);
Description

Gets the AdHoc behavior within a Connection Profile. Allowable values are:

  • WF_ADHOC_CONNECT_THEN_START
  • WF_ADHOC_CONNECT_ONLY
  • WF_ADHOC_START_ONLY
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
adHocBehavior | Pointer to location of the adhoc behavior value for this connection profile.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPGetAdHocBehavior Function


WF_CPGetBssid Function

Contents | Index | Home
Previous | Up | Next
WF_CPGetBssid Function
C
void WF_CPGetBssid(
    UINT8 CpId,
    UINT8 * p_bssid
);
Description

Gets the BSSID element in a Connection Profile.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
p_bssid | Pointer to the BSSID
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPGetBssid Function


WF_CPGetDefaultWepKeyIndex Function

Contents | Index | Home
Previous | Up | Next
WF_CPGetDefaultWepKeyIndex Function
C
void WF_CPGetDefaultWepKeyIndex(
    UINT8 CpId,
    UINT8 * p_defaultWepKeyIndex
);
Description

Only applicable if the Connection Profile security type is either WF_SECURITY_WEP_40 or WF_SECURITY_WEP_104. Selects which of the four WEP keys to use.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
p_defaultWepKeyIndex | Pointer to index of WEP key to use (0 - 3)
Returns

None.

Remarks

Note that only key 0 amongst AP manufacturers is typically used. Using any of the other three keys may be unpredictable from brand to brand.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPGetDefaultWepKeyIndex Function


WF_CPGetElements Function

Contents | Index | Home
Previous | Up | Next
WF_CPGetElements Function
C
void WF_CPGetElements(
    UINT8 CpId,
    tWFCPElements * p_elements
);
Description

Gets all Connection Profile elements for the specified CP ID. If the Host CPU does not have enough memory to create a structure of this size then call the individual get functions.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connectino Profile ID.
p_elements | Pointer to Connection Profile elements structure.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPGetElements Function


WF_CPGetIds Function

Contents | Index | Home
Previous | Up | Next
WF_CPGetIds Function
C
void WF_CPGetIds(
    UINT8 * cpIdList
);
Description

Returns a list of all Connection Profile ID’s that have been created on the MRF24WB0M. This is not to be confused with the Connection Algorithm’s connectionProfileList. This function returns a bit mask corresponding to a list of all Connection Profiles that have been created (whether they are in the connectionProfileList or not). Any Connection Profiles that have been saved to FLASH will be included.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_cpIdList | Pointer to value representing the bit mask where each bit index (plus 1) corresponds to a Connection Profile ID that has been created. For example, if this value is 0x03, then Connection Profile ID’s 1 and and 2 have been created.
Returns

None.

Remarks

the first release will only support two Connection Profiles in memory. Saving CP’s to FLASH will not be supported.

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPGetIds Function


WF_CPGetNetworkType Function

Contents | Index | Home
Previous | Up | Next
WF_CPGetNetworkType Function
C
void WF_CPGetNetworkType(
    UINT8 CpId,
    UINT8 * p_networkType
);
Description

Gets the Network Type element a Connection Profile. Allowable values are:

  • WF_INFRASTRUCTURE
  • WF_ADHOC
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
networkType | Type of network to create (infrastructure or adhoc)
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPGetNetworkType Function


WF_CPGetSecurity Function

Contents | Index | Home
Previous | Up | Next
WF_CPGetSecurity Function
C
void WF_CPGetSecurity(
    UINT8 CpId,
    UINT8 * p_securityType,
    UINT8 * p_wepKeyIndex,
    UINT8 * p_securityKey,
    UINT8 * p_securityKeyLength
);
Description

Configures security for a Connection Profile.

Security | Key | Length
WF_SECURITY_OPEN | N/A | N/A
WF_SECURITY_WEP_40 | hex | 4, 5 byte keys
WF_SECURITY_WEP_104 | hex | 4, 13 byte keys
WF_SECURITY_WPA_WITH_KEY | hex | 32 bytes
WF_SECURITY_WPA_WITH_PASS_PHRASE | ascii | 8-63 ascii characters
WF_SECURITY_WPA2_WITH_KEY | hex | 32 bytes
WF_SECURITY_WPA2_WITH_PASS_PHRASE | ascii | 8-63 ascii characters
WF_SECURITY_WPA_AUTO_WITH_KEY | hex | 32 bytes
WF_SECURITY_WPA_AUTO_WITH_PASS_PHRASE | ascii | 8-63 ascii characters
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
securityType | Value corresponding to the security type desired.
wepKeyIndex | 0 thru 3 (only used if security type is WF_SECURITY_WEP_40 or WF_SECURITY_WEP_104)
p_securityKey | Binary key or passphrase (not used if security is WF_SECURITY_OPEN)
securityKeyLength | Number of bytes in p_securityKey (not used if security is WF_SECURITY_OPEN)
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPGetSecurity Function


WF_CPGetSsid Function

Contents | Index | Home
Previous | Up | Next
WF_CPGetSsid Function
C
void WF_CPGetSsid(
    UINT8 CpId,
    UINT8 * p_ssid,
    UINT8 * p_ssidLength
);
Description

Gets the SSID and SSID Length elements in the Connection Profile.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
p_ssid | Pointer to the SSID string
ssidLength | Pumber of bytes in the SSID
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPGetSsid Function


WF_CPSetAdHocBehavior Function

Contents | Index | Home
Previous | Up | Next
WF_CPSetAdHocBehavior Function
C
void WF_CPSetAdHocBehavior(
    UINT8 CpId,
    UINT8 adHocBehavior
);
Description

Sets the AdHoc behavior within a Connection Profile. Allowable values are:

  • WF_ADHOC_CONNECT_THEN_START
  • WF_ADHOC_CONNECT_ONLY
  • WF_ADHOC_START_ONLY
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
adHocBehavior | Value of the adhoc behavior for this connection profile.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPSetAdHocBehavior Function


WF_CPSetBssid Function

Contents | Index | Home
Previous | Up | Next
WF_CPSetBssid Function
C
void WF_CPSetBssid(
    UINT8 CpId,
    UINT8 * p_bssid
);
Description

Sets the BSSID element in a Connection Profile.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
p_bssid | Pointer to the BSSID
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPSetBssid Function


WF_CPSetDefaultWepKeyIndex Function

Contents | Index | Home
Previous | Up | Next
WF_CPSetDefaultWepKeyIndex Function
C
void WF_CPSetDefaultWepKeyIndex(
    UINT8 CpId,
    UINT8 defaultWepKeyIndex
);
Description

Only applicable if the Connection Profile security type is either WF_SECURITY_WEP_40 or WF_SECURITY_WEP_104. Selects which of the four WEP keys to use.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
defaultWepKeyIndex | Index of WEP key to use (0 - 3)
Returns

None.

Remarks

Note that only key 0 amongst AP manufacturers is typically used. Using any of the other three keys may be unpredictable from brand to brand.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPSetDefaultWepKeyIndex Function


WF_CPSetElements Function

Contents | Index | Home
Previous | Up | Next
WF_CPSetElements Function
C
void WF_CPSetElements(
    UINT8 CpId,
    tWFCPElements * p_elements
);
Description

Sets all Connection Profile elements. If the Host CPU does not have enough memory to create a structure of this size then call the individual set functions.

Preconditions

MACInit must be called.

Parameters
Parameters | Description
CpId | Connectino Profile ID.
p_elements | Pointer to Connection Profile elements structure.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPSetElements Function


WF_CPSetNetworkType Function

Contents | Index | Home
Previous | Up | Next
WF_CPSetNetworkType Function
C
void WF_CPSetNetworkType(
    UINT8 CpId,
    UINT8 networkType
);
Description

Sets the Network Type element a Connection Profile. Allowable values are:

  • WF_INFRASTRUCTURE
  • WF_ADHOC
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
networkType | Type of network to create (infrastructure or adhoc)
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPSetNetworkType Function


WF_CPSetSecurity Function

Contents | Index | Home
Previous | Up | Next
WF_CPSetSecurity Function
C
void WF_CPSetSecurity(
    UINT8 CpId,
    UINT8 securityType,
    UINT8 wepKeyIndex,
    UINT8 * p_securityKey,
    UINT8 securityKeyLength
);
Description

Configures security for a Connection Profile.

Security | Key | Length
WF_SECURITY_OPEN | N/A | N/A
WF_SECURITY_WEP_40 | hex | 4, 5 byte keys
WF_SECURITY_WEP_104 | hex | 4, 13 byte keys
WF_SECURITY_WPA_WITH_KEY | hex | 32 bytes
WF_SECURITY_WPA_WITH_PASS_PHRASE | ascii | 8-63 ascii characters
WF_SECURITY_WPA2_WITH_KEY | hex | 32 bytes
WF_SECURITY_WPA2_WITH_PASS_PHRASE | ascii | 8-63 ascii characters
WF_SECURITY_WPA_AUTO_WITH_KEY | hex | 32 bytes
WF_SECURITY_WPA_AUTO_WITH_PASS_PHRASE | ascii | 8-63 ascii characters
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
securityType | Value corresponding to the security type desired.
wepKeyIndex | 0 thru 3 (only used if security type is WF_SECURITY_WEP_40 or WF_SECURITY_WEP_104)
p_securityKey | Binary key or passphrase (not used if security is WF_SECURITY_OPEN)
securityKeyLength | Number of bytes in p_securityKey (not used if security is WF_SECURITY_OPEN)
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPSetSecurity Function


WF_CPSetSsid Function

Contents | Index | Home
Previous | Up | Next
WF_CPSetSsid Function
C
void WF_CPSetSsid(
    UINT8 CpId,
    UINT8 * p_ssid,
    UINT8 ssidLength
);
Description

Sets the SSID and SSID Length elements in the Connection Profile. Note that if 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 (see scanType field in the Connection Algorithm).

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
p_ssid | Pointer to the SSID string
ssidLength | Number of bytes in the SSID
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WF_CPSetSsid Function


WFCPElementsStruct Structure

Contents | Index | Home
Previous | Up | Next
WFCPElementsStruct Structure
C
struct WFCPElementsStruct {
  UINT8 ssid[WF_MAX_SSID_LENGTH];
  UINT8 bssid[WF_BSSID_LENGTH];
  UINT8 ssidLength;
  UINT8 securityType;
  UINT8 securityKey[WF_MAX_SECURITY_KEY_LENGTH];
  UINT8 securityKeyLength;
  UINT8 wepDefaultKeyId;
  UINT8 networkType;
  UINT8 adHocBehavior;
};
Description

Connection profile elements structure

Members
Members | Description
UINT8 ssid[WF_MAX_SSID_LENGTH]; | SSID, which must be less than or equal to 32 characters. Set to all 0’s if not being used. If ssidLength is 0 this field is ignored. If SSID is not defined then the MRF24WB0M, when using this profile to connect, will scan all channels within its regional domain. Default: SSID not used.
UINT8 bssid[WF_BSSID_LENGTH]; | Basic Service Set Identifier, always 6 bytes. This is the 48-bit MAC of the SSID. It is an optional field that can be used to specify a specific SSID if more than one AP exists with the same SSID. This field can also be used in lieu of the SSID. Set each byte to 0xFF if BSSID is not going to be used. Default: BSSID not used (all FF’s)
UINT8 ssidLength; | Number of ASCII bytes in ssid. Set to 0 is SSID is not going to be used. Default: 0
UINT8 securityType; | Designates the desired security level for the connection. Choices are:
UINT8 securityKey[WF_MAX_SECURITY_KEY_LENGTH]; | Set to NULL if securityType is WF_SECURITY_OPEN. If securityKeyLength is 0 this field is ignored.
UINT8 securityKeyLength; | Number of bytes used in the securityKey. Set to 0 if securityType is WF_SECURITY_OPEN.
UINT8 wepDefaultKeyId; | This field is only used if securityType is WF_SECURITY_WEP. This field designates which of the four WEP keys defined in securityKey to use when connecting to a WiFi network. The range is 0 thru 3, with the default being 0.
UINT8 networkType; | WF_INFRASTRUCTURE or WF_ADHOC Default: WF_INFRASTRUCTURE
UINT8 adHocBehavior; | Only applicable if networkType is WF_ADHOC. Configures Adhoc behavior. Choices are:
Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Public Members > WFCPElementsStruct Structure


Connection Profile Internal Members

Contents | Index | Home
Previous | Up | Next
Connection Profile Internal Members
Functions
Name | Description
LowLevel_CPGetElement | Get an element of the connection profile on the MRF24WB0M.
LowLevel_CPSetElement | Set an element of the connection profile on the MRF24WB0M.
Module

Wi-Fi Connection Profile

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Internal Members


LowLevel_CPGetElement Function

Contents | Index | Home
Previous | Up | Next
LowLevel_CPGetElement Function
C
static void LowLevel_CPGetElement(
    UINT8 CpId,
    UINT8 elementId,
    UINT8 * p_elementData,
    UINT8 elementDataLength,
    UINT8 dataReadAction
);
Description

All Connection Profile 'Get Element' functions call this function to construct the management message. The caller must fix up any endian issues prior to calling this function.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
elementId | Element that is being read
p_elementData | Pointer to where element data will be written
elementDataLength | Number of element data bytes that will be read
dataReadAction | If TRUE then read data per paramters and free mgmt response buffer. If FALSE then return after response received, do not read any data as the caller will do that, and don't free buffer, as caller will do that as well.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Internal Members > LowLevel_CPGetElement Function


LowLevel_CPSetElement Function

Contents | Index | Home
Previous | Up | Next
LowLevel_CPSetElement Function
C
static void LowLevel_CPSetElement(
    UINT8 CpId,
    UINT8 elementId,
    UINT8 * p_elementData,
    UINT8 elementDataLength
);
Description

LOCAL FUNCTION PROTOTYPES

All Connection Profile 'Set Element' functions call this function to construct the management message. The caller must fix up any endian issues prior to calling this function.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | Connection Profile ID
elementId | Element that is being set
p_elementData | Pointer to element data
elementDataLength | Number of bytes pointed to by p_elementData
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Profile > Connection Profile Internal Members > LowLevel_CPSetElement Function


Wi-Fi Connection Algorithm

Contents | Index | Home
Previous | Up | Next
Wi-Fi Connection Algorithm

The connection algorithm is used to fine-tune the MRF24WB0M algorithm used in the connection process. The connection algorithm can only be changed when the MRF24WB0M is not connected to an 802.11 network.

Module

Wi-Fi API

Topics
Name | Description
Connection Algorithm Public Members | Functions and variables accessible by the stack application
Connection Algorithm Internal Members | Functions and variables internal to the module
Wi-Fi API > Wi-Fi Connection Algorithm


Connection Algorithm Public Members

Contents | Index | Home
Previous | Up | Next
Connection Algorithm Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
WF_CAGetBeaconTimeout | Reads the beacon timeout value.
WF_CAGetBeaconTimeoutAction | Reads the Connection Algorithm beacon timeout action.
WF_CAGetChannelList | Gets the channel list.
WF_CAGetConnectionProfileList | Not currently supported
WF_CAGetDeauthAction | Reads the Connection Algorithm deauth action.
WF_CAGetElements | Reads all Connection Algorithm elements.
WF_CAGetEventNotificationAction | Reads the Connection Algorithm event notification action.
WF_CAGetListenInterval | Gets the listen interval.
WF_CAGetListRetryCount | Gets the list retry count
WF_CAGetMaxChannelTime | Gets the Max Channel Time (in milliseconds)
WF_CAGetMinChannelTime | Gets the current Connection Algorithm minimum channel time.
WF_CAGetProbeDelay | Gets the Probe Delay (in microseconds)
WF_CAGetRssi | Gets the RSSI threshold
WF_CAGetScanCount | Gets the scan count
WF_CAGetScanType | Gets the Connection Algorithm scan type
WF_CASetBeaconTimeout | Sets the beacon timeout value.
WF_CASetBeaconTimeoutAction | Action to take if a connection is lost due to a beacon timeout.
WF_CASetChannelList | Sets the channel list.
WF_CASetConnectionProfileList | Not currently supported
WF_CASetDeauthAction | Sets the DeauthAction used by the Connection Algorithm.
WF_CASetElements | Writes all Connection Algorithm elements.
WF_CASetEventNotificationAction | Sets the WiFi events that the host wishes to be notified of.
WF_CASetListenInterval | Sets the listen interval.
WF_CASetListRetryCount | Sets the list retry count
WF_CASetMaxChannelTime | Sets the maximum channel time (in milliseconds)
WF_CASetMinChannelTime | Sets the minimum channel time (in milliseconds)
WF_CASetProbeDelay | Sets the Probe Delay (in microseconds)
WF_CASetRssi | Sets the RSSI threshold
WF_CASetScanCount | Sets the scan count
WF_CASetScanType | Sets the Connection Algorith scan type
Module

Wi-Fi Connection Algorithm

Structures
Name | Description
WFCAElementsStruct | Connection Algorithm Elements
Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members


WF_CAGetBeaconTimeout Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetBeaconTimeout Function
C
void WF_CAGetBeaconTimeout(
    UINT8 * p_beaconTimeout
);
Description

Gets the Beacon Timeout used by the Connection Algorithm.

Value | Description
0 | No monitoring of the beacon timeout condition. The host will not be notified of this event.
1-255 | Number of beacons missed before disconnect event occurs and beaconTimeoutAction occurs. If enabled, host will receive an event message indicating connection temporarily or permanently lost, and if retrying, a connection successful event.
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_beaconTimeout | Pointer where beacon timeout value is written
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetBeaconTimeout Function


WF_CAGetBeaconTimeoutAction Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetBeaconTimeoutAction Function
C
void WF_CAGetBeaconTimeoutAction(
    UINT8 * p_beaconTimeoutAction
);
Description

Gets the Beacon Timeout Action used by the Connection Algorithm.

Preconditions

MACInit must be called first.

Parameters
Parameters
Description
p_beaconTimeoutAction
Pointer where returned value is written. The value
will be either

  • WF_ATTEMPT_TO_RECONNECT
  • WF_DO_NOT_ATTEMPT_TO_RECONNECT

Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetBeaconTimeoutAction Function


WF_CAGetChannelList Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetChannelList Function
C
void WF_CAGetChannelList(
    UINT8 * p_channelList,
    UINT8 * p_numChannels
);
Description

Gets the Channel List used by the Connection Algorithm.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_channelList | Pointer to where channel list will be returned
p_numChannels | Pointer to where number of channels in list will be returned
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetChannelList Function


WF_CAGetConnectionProfileList Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetConnectionProfileList Function
C
void WF_CAGetConnectionProfileList(
    UINT8 cpList[WF_CP_LIST_LENGTH]
);
Description

Not currently supported

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
cpList | Array of connection profile ID's used to create CP list
Returns

None

Remarks

Not currently supported. The list size is always WF_CP_LIST_SIZE.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetConnectionProfileList Function


WF_CAGetDeauthAction Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetDeauthAction Function
C
void WF_CAGetDeauthAction(
    UINT8 * p_deauthAction
);
Description

Gets the DeauthAction used by the Connection Algorithm.

Preconditions

MACInit must be called first.

Parameters
Parameters
Description
p_deauthAction
Pointer where returned value is written. The value will
be either

  • WF_ATTEMPT_TO_RECONNECT
  • WF_DO_NOT_ATTEMPT_TO_RECONNECT

Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetDeauthAction Function


WF_CAGetElements Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetElements Function
C
void WF_CAGetElements(
    tWFCAElements * p_elements
);
Description

Sends a message to the MRF24WB0M which requests all the Connection Algorithm elements.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_elements | Pointer to the output structure (tWFCAElements) where the connection algorithm elements are written.
Returns

None

Remarks

None

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetElements Function


WF_CAGetEventNotificationAction Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetEventNotificationAction Function
C
void WF_CAGetEventNotificationAction(
    UINT8 * p_eventNotificationAction
);
Description

Gets the Event Notification Action used by the Connection Algorithm. The value read back will be a bit mask that corresponds to the following table:

Bit | Event
0 | WF_NOTIFY_CONNECTION_ATTEMPT_SUCCESSFUL
1 | WF_NOTIFY_CONNECTION_ATTEMPT_FAILED
2 | WF_NOTIFY_CONNECTION_TEMPORARILY_LOST
3 | WF_NOTIFY_CONNECTION_PERMANENTLY_LOST
4 | WF_NOTIFY_CONNECTION_REESTABLISHED
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_eventNotificationAction | Pointer to where returned value is written.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetEventNotificationAction Function


WF_CAGetListenInterval Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetListenInterval Function
C
void WF_CAGetListenInterval(
    UINT16 * p_listenInterval
);
Description

Gets the Listen Interval used by the Connection Algorithm. This value is measured in 100ms intervals, the default beacon period of APs.

Value | Description
1 | MRF24WB0M wakes up every 100ms to receive buffered messages.
2 | MRF24WB0M wakes up every 200ms to receive buffered messages.
... | ...
65535 | MRF24WB0M wakes up every 6535.5 seconds (~109 minutes) to receive buffered messages.
Preconditions

MACInit must be called first. Only used when PS Poll mode is enabled.

Parameters
Parameters | Description
p_listenInterval | Pointer to where listen interval is returned
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetListenInterval Function


WF_CAGetListRetryCount Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetListRetryCount Function
C
void WF_CAGetListRetryCount(
    UINT8 * p_listRetryCount
);
Description

See description in WF_CASetListRetryCount()

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_listRetryCount | Pointer to where list retry count is written.
Returns

None

Remarks

None

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetListRetryCount Function


WF_CAGetMaxChannelTime Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetMaxChannelTime Function
C
void WF_CAGetMaxChannelTime(
    UINT16 * p_minChannelTime
);
Description

Gets the maximum time the connection manager waits for a probe response after sending a probe request.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_maxChannelTime | Pointer where maximum channel time is written
Returns

None

Remarks

Default is 400ms

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetMaxChannelTime Function


WF_CAGetMinChannelTime Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetMinChannelTime Function
C
void WF_CAGetMinChannelTime(
    UINT16 * p_minChannelTime
);
Description

Gets the minimum time the connection manager waits for a probe response after sending a probe request.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_minChannelTime | Pointer where minimum time to wait for a probe response (in milliseconds) will be written.
Returns

None

Remarks

None

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetMinChannelTime Function


WF_CAGetProbeDelay Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetProbeDelay Function
C
void WF_CAGetProbeDelay(
    UINT16 * p_probeDelay
);
Description

The number of microseconds to delay before transmitting a probe request following the channel change event.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_probeDelay | Pointer to where probe delay is written
Returns

None

Remarks

Default is 20uS

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetProbeDelay Function


WF_CAGetRssi Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetRssi Function
C
void WF_CAGetRssi(
    UINT8 * p_rssi
);
Description

See WF_CASetRssi. Note that this function only retrieves the RSSI threshold used during the connection -- this is not the current RSSI of an existing connection. If it is desired to retrieve the current RSSI state then a scan must be performed and the scan result will contain the current RSSI state.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_rssi | Pointer to where RSSI value is written
Returns

None

Remarks

Default is 255

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetRssi Function


WF_CAGetScanCount Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetScanCount Function
C
void WF_CAGetScanCount(
    UINT8 * p_scanCount
);
Description

The number of times the Connection Manager will scan a channel while attempting to find a particular WiFi network.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_scanCount | Pointer to where scan count is written
Returns

None

Remarks

Default is 1

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetScanCount Function


WF_CAGetScanType Function

Contents | Index | Home
Previous | Up | Next
WF_CAGetScanType Function
C
void WF_CAGetScanType(
    UINT8 * p_scanType
);
Description

Reads the current Connection Algorithm scan type.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_scanType | Pointer where Connection Algorithm scan type is written.
Returns

None

Remarks

Active scanning causes the MRF24WB0M to send probe requests. Passive scanning implies the MRF24wB0M only listens for beacons. Default is WF_ACTIVE_SCAN.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CAGetScanType Function


WF_CASetBeaconTimeout Function

Contents | Index | Home
Previous | Up | Next
WF_CASetBeaconTimeout Function
C
void WF_CASetBeaconTimeout(
    UINT8 beaconTimeout
);
Description

Sets the Beacon Timeout used by the Connection Algorithm.

Value | Description
0 | No monitoring of the beacon timeout condition. The host will not be notified of this event.
1-255 | Number of beacons missed before disconnect event occurs and beaconTimeoutAction occurs. If enabled, host will receive an event message indicating connection temporarily or permanently lost, and if retrying, a connection successful event.
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
beaconTimeout | Number of beacons that can be missed before the action in beaconTimeoutAction is taken.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetBeaconTimeout Function


WF_CASetBeaconTimeoutAction Function

Contents | Index | Home
Previous | Up | Next
WF_CASetBeaconTimeoutAction Function
C
void WF_CASetBeaconTimeoutAction(
    UINT8 beaconTimeoutAction
);
Description

Sets the Beacon Timeout Action used by the Connection Algorithm.

Preconditions

MACInit must be called first.

Parameters
Parameters
Description
beaconTimeoutAction
Action to take if a connection is lost due
to a beacon timeout. Choices are either

  • WF_ATTEMPT_TO_RECONNECT
  • WF_DO_NOT_ATTEMPT_TO_RECONNECT

Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetBeaconTimeoutAction Function


WF_CASetChannelList Function

Contents | Index | Home
Previous | Up | Next
WF_CASetChannelList Function
C
void WF_CASetChannelList(
    UINT8 * p_channelList,
    UINT8 numChannels
);
Description

Sets the Channel List used by the Connection Algorithm.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_channelList | Pointer to channel list.
numChannels | Number of channels in p_channelList. If set to 0, the MRF24WB0M will use all valid channels for the current regional domain.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetChannelList Function


WF_CASetConnectionProfileList Function

Contents | Index | Home
Previous | Up | Next
WF_CASetConnectionProfileList Function
C
void WF_CASetConnectionProfileList(
    UINT8 cpList[WF_CP_LIST_LENGTH]
);
Description

Not currently supported

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
cpList | Array of connection profile ID's used to create CP list
Returns

None

Remarks

Not currently supported. The list size is always WF_CP_LIST_SIZE. The list should start at index 0. Unused entries in the list must be set to 0xff.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetConnectionProfileList Function


WF_CASetDeauthAction Function

Contents | Index | Home
Previous | Up | Next
WF_CASetDeauthAction Function
C
void WF_CASetDeauthAction(
    UINT8 deauthAction
);
Description

Action to take if a connection is lost due to receiving a deauthentification message from an AP.

Preconditions

MACInit must be called first.

Parameters
Parameters
Description
deauthAction
Action to take in the event of a deauthentication.
Allowable values are

  • WF_ATTEMPT_TO_RECONNECT
  • WF_DO_NOT_ATTEMPT_TO_RECONNECT

Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetDeauthAction Function


WF_CASetElements Function

Contents | Index | Home
Previous | Up | Next
WF_CASetElements Function
C
void WF_CASetElements(
    tWFCAElements * p_elements
);
Description

Connection Algorithm Functions

Sends a message to the MRF24WB0M which sets all the Connection Algorithm elements.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_elements | Pointer to the input structure (tWFCAElements) containing the connection algorithm elements.
Returns

None

Remarks

None

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetElements Function


WF_CASetEventNotificationAction Function

Contents | Index | Home
Previous | Up | Next
WF_CASetEventNotificationAction Function
C
void WF_CASetEventNotificationAction(
    UINT8 eventNotificationAction
);
Description

Sets the Event Notification Action used by the Connection Algorithm. The bit mask for the allowable entries is as follows:

Bit | Event
0 | WF_NOTIFY_CONNECTION_ATTEMPT_SUCCESSFUL
1 | WF_NOTIFY_CONNECTION_ATTEMPT_FAILED
2 | WF_NOTIFY_CONNECTION_TEMPORARILY_LOST
3 | WF_NOTIFY_CONNECTION_PERMANENTLY_LOST
4 | WF_NOTIFY_CONNECTION_REESTABLISHED
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
eventNotificationAction | Bit mask indicating which events the host wants to be notifed of.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetEventNotificationAction Function


WF_CASetListenInterval Function

Contents | Index | Home
Previous | Up | Next
WF_CASetListenInterval Function
C
void WF_CASetListenInterval(
    UINT16 listenInterval
);
Description

Sets the listen interval used by the Connection Algorithm. This value is measured in 100ms intervals, the default beacon period of APs.

Value | Description
1 | MRF24WB0M wakes up every 100ms to receive buffered messages.
2 | MRF24WB0M wakes up every 200ms to receive buffered messages.
... | ...
65535 | MRF24WB0M wakes up every 6535.5 seconds (~109 minutes) to receive buffered messages.
Preconditions

MACInit must be called first. Only used when PS Poll mode is enabled.

Parameters
Parameters | Description
listenInterval | Number of 100ms intervals between instances when the MRF24WB0M wakes up to receive buffered messages from the network.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetListenInterval Function


WF_CASetListRetryCount Function

Contents | Index | Home
Previous | Up | Next
WF_CASetListRetryCount Function
C
void WF_CASetListRetryCount(
    UINT8 listRetryCount
);
Description

Number of times to cycle through Connection Profile List before giving up on the connection attempt. Since lists are not yet supported, this function actually sets the number of times the Connection Manager will try to connect with the current Connection Profile before giving up.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
listRetryCount | 0 to 254 or WF_RETRY_FOREVER (255)
Returns

None

Remarks

None

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetListRetryCount Function


WF_CASetMaxChannelTime Function

Contents | Index | Home
Previous | Up | Next
WF_CASetMaxChannelTime Function
C
void WF_CASetMaxChannelTime(
    UINT16 minChannelTime
);
Description

The maximum time (in milliseconds) the connection manager will wait for a probe response after sending a probe request. If no probe responses are received in maxChannelTime then the connection manager will go on to the next channel, if any are left to scan, or quit.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
maxChannelTime | Maximum time to wait for a probe response (in milliseconds)
Returns

None

Remarks

Default is 400ms

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetMaxChannelTime Function


WF_CASetMinChannelTime Function

Contents | Index | Home
Previous | Up | Next
WF_CASetMinChannelTime Function
C
void WF_CASetMinChannelTime(
    UINT16 minChannelTime
);
Description

The minimum time (in milliseconds) the connection manager will wait for a probe response after sending a probe request. If no probe responses are received in minChannelTime then the connection manager will go on to the next channel, if any are left to scan, or quit.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
minChannelTime | Minimum time to wait for a probe response (in milliseconds)
Returns

None

Remarks

Default is 200ms

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetMinChannelTime Function


WF_CASetProbeDelay Function

Contents | Index | Home
Previous | Up | Next
WF_CASetProbeDelay Function
C
void WF_CASetProbeDelay(
    UINT16 probeDelay
);
Description

The number of microseconds to delay before transmitting a probe request following the channel change event.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
probeDelay | Desired probe delay
Returns

None

Remarks

Default is 20uS

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetProbeDelay Function


WF_CASetRssi Function

Contents | Index | Home
Previous | Up | Next
WF_CASetRssi Function
C
void WF_CASetRssi(
    UINT8 rssi
);
Description

Specifies the RSSI behavior when connecting. This value is only used if 1) The current Connection Profile has not defined an SSID or BSSID 2) An SSID is defined in the current Connection Profile and multiple access points are discovered with the same SSID.

Values: 0 : Connect to the first network found 1 - 254: Only connect to a network if the RSSI is greater than or equal to the specified value 255: Connect to the highest RSSI found

Note that RSSI is a relative value with no units -- it is not correlated to dBm.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
scanCount | Desired scan count
Returns

None

Remarks

Default is 255

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetRssi Function


WF_CASetScanCount Function

Contents | Index | Home
Previous | Up | Next
WF_CASetScanCount Function
C
void WF_CASetScanCount(
    UINT8 scanCount
);
Description

The number of times the Connection Manager will scan a channel while attempting to find a particular WiFi network.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
scanCount | Desired scan count
Returns

None

Remarks

Default is 1

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetScanCount Function


WF_CASetScanType Function

Contents | Index | Home
Previous | Up | Next
WF_CASetScanType Function
C
void WF_CASetScanType(
    UINT8 scanType
);
Description

Configures the Connection Algorithm for the desired scan type.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
scanType | Desired scan type. Either WF_ACTIVE_SCAN or WF_PASSIVE_SCAN.
Returns

None

Remarks

Active scanning causes the MRF24WB0M to send probe requests. Passive scanning implies the MRF24WB0M only listens for beacons. Default is WF_ACTIVE_SCAN.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WF_CASetScanType Function


WFCAElementsStruct Structure

Contents | Index | Home
Previous | Up | Next
WFCAElementsStruct Structure
C
struct WFCAElementsStruct {
  UINT16 listenInterval;
  UINT8 scanType;
  UINT8 rssi;
  UINT8 connectionProfileList[WF_CP_LIST_LENGTH];
  UINT8 listRetryCount;
  UINT8 eventNotificationAction;
  UINT8 beaconTimeoutAction;
  UINT8 deauthAction;
  UINT8 channelList[WF_CHANNEL_LIST_LENGTH];
  UINT8 numChannelsInList;
  UINT8 beaconTimeout;
  UINT8 scanCount;
  UINT8 pad1;
  UINT16 minChannelTime;
  UINT16 maxChannelTime;
  UINT16 probeDelay;
};
Description

Connection Algorithm Elements

Members
Members
Description
UINT16 listenInterval;
This parameter is only used when PS Poll mode is enabled. See WF_PsPollEnable(). Number of 100ms intervals between instances when the MRF24WB0M wakes up to received buffered messages from the network. Range is from 1 (100ms) to 6553.5 sec (~109 min).
Note that the 802.11 standard defines the listen interval in terms of Beacon Periods, which are typically 100ms. If the MRF24WB0M is communicating to a network with a network that has Beacon Periods that is not 100ms it will round up (or down) as needed to match the actual Beacon Period as closely as possible.
Important Note: If the listenInterval is modified while connected to a network the MRF24WB0M will automatically reconnect to the network with the new Beacon Period value. This may cause a temporary loss of data packets.
UINT8 scanType;
WF_ACTIVE_SCAN (Probe Requests sent out) or WF_PASSIVE_SCAN (listen only)
Default: WF_ACTIVE_SCAN
UINT8 rssi;
Specifies RSSI restrictions when connecting. This field is only used if:

  1. The Connection Profile has not defined a SSID or BSSID, or
  2. An SSID is defined in the Connection Profile and multiple AP’s are discovered with the same SSID.

UINT8 connectionProfileList[WF_CP_LIST_LENGTH];
Note: Connection Profile lists are not yet supported. This array should be set to all FF’s.
UINT8 listRetryCount;
This field is used to specify the number of retries for the single connection profile before taking the connection lost action.
Range 1 to 254 or WF_RETRY_FOREVER (255)
Default is 3
UINT8 eventNotificationAction;
There are several connection-related events that can occur. The Host has the option to be notified (or not) when some of these events occur. This field controls event notification for connection-related events.
UINT8 beaconTimeoutAction;
Specifies the action the Connection Manager should take if a Connection is lost due to a Beacon Timeout. If this field is set to WF_ATTEMPT_TO_RECONNECT then the number of attempts is limited to the value in listRetryCount.
Choices are: WF_ATTEMPT_TO_RECONNECT or WF_DO_NOT_ATTEMPT_TO_RECONNECT
Default: WF_ATTEMPT_TO_RECONNECT
UINT8 deauthAction;
Designates what action the Connection Manager should take if it receives a Deauthentication message from the AP.
If this field is set to WF_ATTEMPT_TO_RECONNECT then the number of attempts is limited to the value in listRetryCount.
Choices are: WF_ATTEMPT_TO_RECONNECT or WF_DO_NOT_ATTEMPT_TO_RECONNECT
Default: WF_ATTEMPT_TO_RECONNECT
UINT8 channelList[WF_CHANNEL_LIST_LENGTH];
List of one or more channels that the MRF24WB0M should utilize when connecting or scanning. If numChannelsInList is set to 0 then this parameter should be set to NULL.
Default: All valid channels for the regional domain of the MRF24WB0M (set at manufacturing).
UINT8 numChannelsInList;
Number of channels in channelList. If set to 0 then the MRF24WB0M will populate the list with all valid channels for the regional domain.
Default: The number of valid channels for the regional domain of the MRF24WB0M (set at manufacturing).
UINT8 beaconTimeout;
Specifies the number of beacons that can be missed before the action described in beaconTimeoutAction is taken.
UINT8 scanCount;
The number of times to scan a channel while attempting to find a particular access point.
Default: 1
UINT16 minChannelTime;
The minimum time (in milliseconds) the connection manager will wait for a probe response after sending a probe request. If no probe responses are received in minChannelTime then the connection manager will go on to the next channel, if any are left to scan, or quit.
Default: 200ms
UINT16 maxChannelTime;
If a probe response is received within minChannelTime then the connection manager 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: 400ms
UINT16 probeDelay;
The number of microseconds to delay before transmitting a probe request following the channel change event.
Default: 20us
Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Public Members > WFCAElementsStruct Structure


Connection Algorithm Internal Members

Contents | Index | Home
Previous | Up | Next
Connection Algorithm Internal Members

The following functions and variables are designated as internal to the module.

Functions
Name | Description
LowLevel_CAGetElement | Get an element of the connection algorithm on the MRF24WB0M.
LowLevel_CASetElement | Set an element of the connection algorithm on the MRF24WB0M.
SetEventNotificationMask | Sets the event notification mask.
Module

Wi-Fi Connection Algorithm

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Internal Members


LowLevel_CAGetElement Function

Contents | Index | Home
Previous | Up | Next
LowLevel_CAGetElement Function
C
static void LowLevel_CAGetElement(
    UINT8 elementId,
    UINT8 * p_elementData,
    UINT8 elementDataLength,
    UINT8 dataReadAction
);
Description

Low-level function to send the appropriate management message to the MRF24WB0M to get the Connection Algorithm element.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
elementId | Element that is being read
p_elementData | Pointer to where element data will be written
elementDataLength | Number of element data bytes that will be read
dataReadAction | If TRUE then read data per paramters and free mgmt response buffer. If FALSE then return after response received, do not read any data as the caller will do that, and don't free buffer, as caller will do that as well.
Returns

None.

Remarks

All Connection Algorithm 'Get Element' functions call this function to construct the management message. The caller must fix up any endian issues after getting the data from this function.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Internal Members > LowLevel_CAGetElement Function


LowLevel_CASetElement Function

Contents | Index | Home
Previous | Up | Next
LowLevel_CASetElement Function
C
static void LowLevel_CASetElement(
    UINT8 elementId,
    UINT8 * p_elementData,
    UINT8 elementDataLength
);
Description

LOCAL FUNCTION PROTOTYPES

Low-level function to send the appropriate management message to the MRF24WB0M to set the Connection Algorithm element.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
elementId | Element that is being set
p_elementData | Pointer to element data
elementDataLength | Number of bytes pointed to by p_elementData
Returns

None.

Remarks

All Connection Algorithm 'Set Element' functions call this function to construct the management message. The caller must fix up any endian issues prior to calling this function.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Internal Members > LowLevel_CASetElement Function


SetEventNotificationMask Function

Contents | Index | Home
Previous | Up | Next
SetEventNotificationMask Function
C
static void SetEventNotificationMask(
    UINT8 eventNotificationBitMask
);
Description

Sets the event notification mask for the Connection Algorithm. Allowable values are:

Value | Event
0x01 | WF_NOTIFY_CONNECTION_ATTEMPT_SUCCESSFUL
0x02 | WF_NOTIFY_CONNECTION_ATTEMPT_FAILED
0x04 | WF_NOTIFY_CONNECTION_TEMPORARILY_LOST
0x08 | WF_NOTIFY_CONNECTION_PERMANENTLY_LOST
0x10 | WF_NOTIFY_CONNECTION_REESTABLISHED
0x1f | WF_NOTIFY_ALL_EVENTS
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
eventNotificationBitMask | Bit mask defining which events the host will be notified of.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Algorithm > Connection Algorithm Internal Members > SetEventNotificationMask Function


Wi-Fi Connection Manager

Contents | Index | Home
Previous | Up | Next
Wi-Fi Connection Manager

The connection manager uses the connection algorithm and one or more connection profiles to connect to a network.

Module

Wi-Fi API

Topics
Name | Description
Connection Manager Public Members | Functions and variables accessible by the stack application
Wi-Fi API > Wi-Fi Connection Manager


Connection Manager Public Members

Contents | Index | Home
Previous | Up | Next
Connection Manager Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
WF_CMConnect | Commands the MRF24WB0M to start a connection.
WF_CMDisconnect | Commands the MRF24WB0M to close any open connections and/or to cease attempting to connect.
WF_CMGetConnectionState | Returns the current connection state.
WF_CMInfoGetFSMStats | CM Info Functions
Module

Wi-Fi Connection Manager

Wi-Fi API > Wi-Fi Connection Manager > Connection Manager Public Members


WF_CMConnect Function

Contents | Index | Home
Previous | Up | Next
WF_CMConnect Function
C
void WF_CMConnect(
    UINT8 CpId
);
Description

Connection Manager Functions

Directs the Connection Manager to scan for and connect to a WiFi network. This function does not wait until the connection attempt is successful, but returns immediately. See WF_ProcessEvent for events that can occur as a result of a connection attempt being successful or not.

Note that if the Connection Profile being used has WPA or WPA2 security enabled and is using a passphrase, the connection manager will first calculate the PSK key, and then start the connection process. The key calculation can take up to 30 seconds.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
CpId | If this value is equal to an existing Connection Profile’s ID than only that Connection Profile will be used to attempt a connection to a WiFi network. If this value is set to WF_CM_CONNECT_USING_LIST then the connectionProfileList will be used to connect, starting with the first Connection Profile in the list.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Manager > Connection Manager Public Members > WF_CMConnect Function


WF_CMDisconnect Function

Contents | Index | Home
Previous | Up | Next
WF_CMDisconnect Function
C
void WF_CMDisconnect();
Description

Directs the Connection Manager to close any open connection or connection attempt in progress. No further attempts to connect are taken until WF_CMConnect() is called. Generates the event WF_EVENT_CONNECTION_PERMANENTLY_LOST when the connection is successfully terminated.

Preconditions

MACInit must be called.

Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Manager > Connection Manager Public Members > WF_CMDisconnect Function


WF_CMGetConnectionState Function

Contents | Index | Home
Previous | Up | Next
WF_CMGetConnectionState Function
C
void WF_CMGetConnectionState(
    UINT8 * p_state,
    UINT8 * p_currentCpId
);
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_state | Pointer to location where connection state will be written
p_currentCpId | Pointer to location of current connection profile ID that is being queried.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Connection Manager > Connection Manager Public Members > WF_CMGetConnectionState Function


WF_CMInfoGetFSMStats Function

Contents | Index | Home
Previous | Up | Next
WF_CMInfoGetFSMStats Function
C
void WF_CMInfoGetFSMStats(
    tWFCMInfoFSMStats * p_info
);
Description

CM Info Functions

Wi-Fi API > Wi-Fi Connection Manager > Connection Manager Public Members > WF_CMInfoGetFSMStats Function


Wi-Fi Scan

Contents | Index | Home
Previous | Up | Next
Wi-Fi Scan

If the application already knows the network SSID that it wants to join than it can set up a connection profile with that information and attempt to join the network. However, there are applications that first need to dynamically determine what infrastructure and/or adhoc networks are in the area, and then decide which network to join. The scan API functions are used to gather this information.

Module

Wi-Fi API

Topics
Name | Description
Scan Public Members | Functions and variables accessible by the stack application
Wi-Fi API > Wi-Fi Scan


Scan Public Members

Contents | Index | Home
Previous | Up | Next
Scan Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
WF_Scan | Commands the MRF24WB0M to start a scan operation. This will generate the WF_EVENT_SCAN_RESULTS_READY event.
WF_ScanGetResult | Read scan results back from MRF24WB0M.
Module

Wi-Fi Scan

Wi-Fi API > Wi-Fi Scan > Scan Public Members


WF_Scan Function

Contents | Index | Home
Previous | Up | Next
WF_Scan Function
C
void WF_Scan(
    UINT8 CpId
);
Description

Scan Functions

Directs the MRF24WB0M to initiate a scan operation utilizing the input Connection Profile ID. The Host Application will be notified that the scan results are ready when it 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 WF_ScanGetResult().

Scan results are retained on the MRF24WB0M until:

  1. Calling WF_Scan() again (after scan results returned from previous call).
  2. MRF24WB0M reset.
Preconditions

MACInit must be called first.

Parameters
Parameters
Description
CpId
Connection Profile to use. If the CpId is valid then the values from that Connection Profile will be used for filtering scan results. If the CpId is set to WF_SCAN_ALL (0xFF) then a default filter will be used.
Valid CpId

  • If CP has a defined SSID only scan results with that SSID are retained.
  • If CP does not have a defined SSID then all scanned SSID’s will be retained
  • Only scan results from Infrastructure or AdHoc networks are retained, depending on the value of networkType in the Connection Profile
  • The channel list that is scanned will be determined from channelList in the Connection Algorithm (which must be defined before calling this function).

CpId is equal to WF_SCAN_ALL

  • All scan results are retained (both Infrastructure and Ad Hoc networks).
  • All channels within the MRF24WB0M’s regional domain will be scanned.
  • No Connection Profiles need to be defined before calling this function.
  • The Connection Algorithm does not need to be defined before calling this function.

Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Scan > Scan Public Members > WF_Scan Function


WF_ScanGetResult Function

Contents | Index | Home
Previous | Up | Next
WF_ScanGetResult Function
C
void WF_ScanGetResult(
    UINT8 listIndex,
    tWFScanResult * p_scanResult
);
Description

After a scan has completed this function is used to read one or more of the scan results from the MRF24WB0M. The scan results will be written contiguously starting at p_scanResults (see tWFScanResult structure for format of scan result).

Preconditions

MACInit must be called first. 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 location to store the scan result structure
Retrieve RSSI | RSSI_MAX (200) , RSSI_MIN (106) p_scanResult->rssi
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Scan > Scan Public Members > WF_ScanGetResult Function


Wi-Fi Tx Power Control

Contents | Index | Home
Previous | Up | Next
Wi-Fi Tx Power Control

The API functions in this section are used to configure the MRF24WB0M Tx power control settings.

An application can control Tx power by modify the max Tx power via WF_TxPowerSetMinMax() to something other than 10dBm.

Module

Wi-Fi API

Topics
Name | Description
Tx Power Control Public Members | Functions and variables accessible by the stack application
Wi-Fi API > Wi-Fi Tx Power Control


Tx Power Control Public Members

Contents | Index | Home
Previous | Up | Next
Tx Power Control Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
WF_TxPowerGetMinMax | Gets the Tx min and max power on the MRF24WB0M.
WF_TxPowerSetMinMax | Sets the Tx min and max power on the MRF24WB0M.
WF_TxPowerGetFactoryMax | Retrieves the factory-set max Tx power from the MRF24WB0M.
Module

Wi-Fi Tx Power Control

Wi-Fi API > Wi-Fi Tx Power Control > Tx Power Control Public Members


WF_TxPowerGetMinMax Function

Contents | Index | Home
Previous | Up | Next
WF_TxPowerGetMinMax Function
C
void WF_TxPowerGetMinMax(
    INT8 * p_minTxPower,
    INT8 * p_maxTxPower
);
Description

After initialization the MRF24WB0M max Tx power is determined by a factory-set value. This function can set a different minimum and 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 WF_TxPowerGetFactoryMax().

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_minTxPower | Pointer to location to write the minTxPower
p_maxTxPower | Pointer to location to write the maxTxPower
Returns

None.

Remarks

No conversion of units needed, input to MRF24WB0M is in dB.

Wi-Fi API > Wi-Fi Tx Power Control > Tx Power Control Public Members > WF_TxPowerGetMinMax Function


WF_TxPowerSetMinMax Function

Contents | Index | Home
Previous | Up | Next
WF_TxPowerSetMinMax Function
C
void WF_TxPowerSetMinMax(
    INT8 minTxPower,
    INT8 maxTxPower
);
Description

Tx Power Control Functions

After initialization the MRF24WB0M max Tx power is determined by a factory-set value. This function can set a different minimum and 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 WF_TxPowerGetFactoryMax().

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
minTxPower | Desired minTxPower (-10 to 10dB)
maxTxPower | Desired maxTxPower (-10 to 10dB)
Returns

None.

Remarks

No conversion of units needed, input to MRF24WB0M is in dB.

Wi-Fi API > Wi-Fi Tx Power Control > Tx Power Control Public Members > WF_TxPowerSetMinMax Function


WF_TxPowerGetFactoryMax Function

Contents | Index | Home
Previous | Up | Next
WF_TxPowerGetFactoryMax Function
C
void WF_TxPowerGetFactoryMax(
    INT8 * p_factoryMaxTxPower
);
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_factoryMaxTxPower | Desired maxTxPower (-10 to 10dB), in 1dB steps
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Tx Power Control > Tx Power Control Public Members > WF_TxPowerGetFactoryMax Function


Wi-Fi Power Save

Contents | Index | Home
Previous | Up | Next
Wi-Fi Power Save

The MRF24WB0M supports two power-saving modes – sleep and hibernate.

Mode | Description
Sleep | This mode is used when in PS Poll mode where the MRF24WB0M wakes itself up at periodic intervals to query the network for receive messages buffered by an Access Point. See listenInterval in the tWFCAElements structure. When in sleep mode the MRF24WB0M transmitter receiver circuits are turned off along with other circuitry to minimize power consumption. Sleep mode is entered periodically as a result of the Host CPU enabling PS Poll mode.
Hibernate | This mode effectively turns the MRF24WB0M off for maximum power savings. MRF24WB0M state is not retained, and when the MRF24WB0M is taken out of the Hibernate state it performs a reboot. Hibernate mode is controlled by toggling the XCEN33 pin on the MRF24WB0M module (high to enter hibernate, low to exit). This mode should be used when the application allows for the MRF24WB0M module to be off for extended periods of time.
Power Save Functions

802.11 chipsets have two well known operational power modes. Active power mode is defined as the radio always on either transmitting or receiving, meaning that when it isn't transmitting then it is trying to receive. Power save mode is defined as operating with the radio turned off when there is nothing to transmit and only turning the radio receiver on when required.

The power save mode is a mode that requires interaction with an Access Point. The access point is notified via a packet from the Station that it is entering into power save mode. As a result the access point is required to buffer any packets that are destined for the Station until the Station announces that it is ready to once again receive packets. The duration that a Station is allowed to remain in this mode is limited and is typically 10 times the beacon interval of the Access point.

If the host is expecting packets from the network it should operate in Active mode. If however power saving is critical and packets are not expected then the host should consider operating in power save mode. Due to the nature of Access points not all behaving the same, there is the possibility that an Access point will invalidate a Stations connection if it has not heard from the Station over a given time period. For this reason power save mode should be used with caution.

The 802.11 name for power saving mode is PS-Poll (Power-Save Poll).

Module

Wi-Fi API

Topics
Name | Description
Power Save Public Members | Functions and variables accessible by the stack application
Power Save Internal Members | Functions and variables internal to the module
Wi-Fi API > Wi-Fi Power Save


Power Save Public Members

Contents | Index | Home
Previous | Up | Next
Power Save Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
WF_GetPowerSaveState | Returns current power-save state.
WF_HibernateEnable | Puts the MRF24WB0M into hibernate mode.
WF_PsPollDisable | Disables PS-Poll mode.
WF_PsPollEnable | Enables PS Poll mode.
Module

Wi-Fi Power Save

Wi-Fi API > Wi-Fi Power Save > Power Save Public Members


WF_GetPowerSaveState Function

Contents | Index | Home
Previous | Up | Next
WF_GetPowerSaveState Function
C
void WF_GetPowerSaveState(
    UINT8 * p_powerSaveState
);
Description

Returns the current MRF24WB0M power save state.

Value Definition

---- ---------

WF_PS_HIBERNATE MRF24WB0M in hibernate state
WF_PS_PS_POLL_DTIM_ENABLED MRF24WB0M in PS-Poll mode with DTIM enabled
WF_PS_PS_POLL_DTIM_DISABLED MRF24WB0M in PS-Poll mode with DTIM disabled
WF_PS_POLL_OFF MRF24WB0M is not in any power-save state
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_powerSaveState | Pointer to where power state is written
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Power Save > Power Save Public Members > WF_GetPowerSaveState Function


WF_HibernateEnable Function

Contents | Index | Home
Previous | Up | Next
WF_HibernateEnable Function
C
void WF_HibernateEnable();
Description

Enables Hibernate mode on the MRF24WB0M, which effectively turns off the device for maximum power savings.

MRF24WB0M state is not maintained when it transitions to hibernate mode. To remove the MRF24WB0M from hibernate mode call WF_Init().

Preconditions

MACInit must be called first.

Returns

None.

Remarks

Note that because the MRF24WB0M does not save state, there will be a disconnect between the TCP/IP stack and the MRF24B0M state. If it is desired by the application to use hibernate, additional measures must be taken to save application state. Then the host should be reset. This will ensure a clean connection between MRF24WB0M and TCP/IP stack

Future versions of the stack might have the ability to save stack context as well, ensuring a clean wake up for the MRF24WB0M without needing a host reset.

Wi-Fi API > Wi-Fi Power Save > Power Save Public Members > WF_HibernateEnable Function


WF_PsPollDisable Function

Contents | Index | Home
Previous | Up | Next
WF_PsPollDisable Function
C
void WF_PsPollDisable();
Description

Power Management Functions

Disables PS Poll mode. The MRF24WB0M will stay active and not go sleep.

Preconditions

MACInit must be called first.

Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Power Save > Power Save Public Members > WF_PsPollDisable Function


WF_PsPollEnable Function

Contents | Index | Home
Previous | Up | Next
WF_PsPollEnable Function
C
void WF_PsPollEnable(
    BOOL rxDtim
);
Description

Enables PS Poll mode. PS-Poll (Power-Save Poll) is a mode allowing for longer battery life. The MRF24WB0M 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 MRF24WB0M to wake up each time the Host sends Tx data or a control message to the MRF24WB0M. When the Host message transaction is complete the MRF24WB0M 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

MACInit must be called first.

Parameters
Parameters | Description
rxDtim | TRUE if MRF24WB0M should wake up periodically and check for buffered broadcast messages, else FALSE
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Power Save > Power Save Public Members > WF_PsPollEnable Function


Power Save Internal Members

Contents | Index | Home
Previous | Up | Next
Power Save Internal Members

The following functions and variables are designated as internal to the module.

Functions
Name | Description
SendPowerModeMsg | Send power mode management message to the MRF24WB0M.
SetPowerSaveState | Sets the desired power save state of the MRF24WB0M.
Module

Wi-Fi Power Save

Wi-Fi API > Wi-Fi Power Save > Power Save Internal Members


SendPowerModeMsg Function

Contents | Index | Home
Previous | Up | Next
SendPowerModeMsg Function
C
static void SendPowerModeMsg(
    tWFPwrModeReq * p_powerMode
);
Description

LOCAL FUNCTION PROTOTYPES

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_powerMode | Pointer to tWFPwrModeReq structure to send to MRF24WB0M.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Power Save > Power Save Internal Members > SendPowerModeMsg Function


SetPowerSaveState Function

Contents | Index | Home
Previous | Up | Next
SetPowerSaveState Function
C
static void SetPowerSaveState(
    UINT8 powerSaveState
);
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
powerSaveState | Value of the power save state desired.
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Power Save > Power Save Internal Members > SetPowerSaveState Function


Wi-Fi Miscellaneous

Contents | Index | Home
Previous | Up | Next
Wi-Fi Miscellaneous
Module

Wi-Fi API

Topics
Name | Description
Wi-Fi Miscellaneous Public Members | Functions and variables accessible by the stack application
Wi-Fi API > Wi-Fi Miscellaneous


Wi-Fi Miscellaneous Public Members

Contents | Index | Home
Previous | Up | Next
Wi-Fi Miscellaneous Public Members

The following functions and variables are available to the stack application.

Functions
Name | Description
WF_GetDeviceInfo | Retrieves WF device information
WF_GetMacAddress | Retrieves the MRF24WB0M MAC address
WF_GetMacStats | Gets MAC statistics.
WF_GetMultiCastFilter | Gets a multicast address filter from one of the two multicast filters.
WF_GetRegionalDomain | Retrieves the MRF24WB0M Regional domain
WF_GetRtsThreshold | Gets the RTS Threshold
WF_SetMacAddress | Uses a different MAC address for the MRF24WB0M
WF_SetMultiCastFilter | Sets a multicast address filter using one of the two multicast filters.
WF_SetRegionalDomain | Enables or disables the MRF24WB0M Regional Domain.
WF_SetRtsThreshold | Sets the RTS Threshold.
Module

Wi-Fi Miscellaneous

Structures
Name | Description
tWFDeviceInfoStruct | used in WF_GetDeviceInfo
WFMacStatsStruct | This is record WFMacStatsStruct.
Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members


WF_GetDeviceInfo Function

Contents | Index | Home
Previous | Up | Next
WF_GetDeviceInfo Function
C
void WF_GetDeviceInfo(
    tWFDeviceInfo * p_deviceInfo
);
Description

Version functions

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_deviceInfo | Pointer where device info will be written
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_GetDeviceInfo Function


WF_GetMacAddress Function

Contents | Index | Home
Previous | Up | Next
WF_GetMacAddress Function
C
void WF_GetMacAddress(
    UINT8 * p_mac
);
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_mac | Pointer where mac will be written (must point to a 6-byte buffer)
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_GetMacAddress Function


WF_GetMacStats Function

Contents | Index | Home
Previous | Up | Next
WF_GetMacStats Function
C
void WF_GetMacStats(
    tWFMacStats * p_macStats
);
Description

MAC Stats

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_macStats | Pointer to where MAC statistics are written
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_GetMacStats Function


WF_GetMultiCastFilter Function

Contents | Index | Home
Previous | Up | Next
WF_GetMultiCastFilter Function
C
void WF_GetMultiCastFilter(
    UINT8 multicastFilterId,
    UINT8 multicastAddress[6]
);
Description

Gets the current state of the specified Multicast Filter.

Normally would call SendGetParamMsg, but this GetParam returns all 6 address filters + 2 more bytes for a total of 48 bytes plus header. So, doing this msg manually to not require a large stack allocation to hold all the data.

Exact format of returned message is: [0] -- always mgmt response (2) [1] -- always WF_GET_PARAM_SUBTYPE (16) [2] -- result (1 if successful) [3] -- mac state (not used) [4] -- data length (length of response data starting at index 6) [5] -- not used [6-11] -- Compare Address 0 address [12] -- Compare Address 0 group [13] -- Compare Address 0 type [14-19] -- Compare Address 1 address [20] -- Compare Address 1 group [21] -- Compare Address 1 type [22-27] -- Compare Address 2 address [28] -- Compare Address 2 group [29] -- Compare Address 2 type [30-35] -- Compare Address 3 address [36] -- Compare Address 3 group [37] -- Compare Address 3 type [38-43] -- Compare Address 4 address [44] -- Compare Address 4 group [45] -- Compare Address 4 type [46-51] -- Compare Address 5 address [52] -- Compare Address 5 group [53] -- Compare Address 5 type

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
multicastFilterId | WF_MULTICAST_FILTER_1 or WF_MULTICAST_FILTER_2
multicastAddress | 6-byte address
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_GetMultiCastFilter Function


WF_GetRegionalDomain Function

Contents | Index | Home
Previous | Up | Next
WF_GetRegionalDomain Function
C
void WF_GetRegionalDomain(
    UINT8 * p_regionalDomain
);
Description

see tWFRegDomain enumerated types

Gets the regional domain on the MRF24WB0M. Allowable values are:

  • WF_DOMAIN_FCC
  • WF_DOMAIN_IC
  • WF_DOMAIN_ETSI
  • WF_DOMAIN_SPAIN
  • WF_DOMAIN_FRANCE
  • WF_DOMAIN_JAPAN_A
  • WF_DOMAIN_JAPAN_B
Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_regionalDomain | Pointer where the regional domain value will be written
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_GetRegionalDomain Function


WF_GetRtsThreshold Function

Contents | Index | Home
Previous | Up | Next
WF_GetRtsThreshold Function
C
void WF_GetRtsThreshold(
    UINT16 * p_rtsThreshold
);
Description

Gets the RTS/CTS packet size threshold.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
p_rtsThreshold | Pointer to where RTS threshold is written
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_GetRtsThreshold Function


WF_SetMacAddress Function

Contents | Index | Home
Previous | Up | Next
WF_SetMacAddress Function
C
void WF_SetMacAddress(
    UINT8 * p_mac
);
Description

MAC Address Functions

Directs the MRF24WB0M 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 – it simply tells the MRF24WB0M to use a different MAC.

Preconditions

MACInit must be called first. Cannot be called when the MRF24WB0M is in a connected state.

Parameters
Parameters | Description
p_mac | Pointer to 6-byte MAC that will be sent to MRF24WB0M
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_SetMacAddress Function


WF_SetMultiCastFilter Function

Contents | Index | Home
Previous | Up | Next
WF_SetMultiCastFilter Function
C
void WF_SetMultiCastFilter(
    UINT8 multicastFilterId,
    UINT8 multicastAddress[6]
);
Description

Multicast Functions

This function allows the application to configure up to two Multicast Address Filters on the MRF24WB0M. If two active multicast filters are set up they are OR’d together – the MRF24WB0M will receive and pass to the Host CPU received packets from either multicast address. The allowable values for the multicast filter are:

  • WF_MULTICAST_FILTER_1
  • WF_MULTICAST_FILTER_2

By default, both Multicast Filters are inactive.

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
multicastFilterId | WF_MULTICAST_FILTER_1 or WF_MULTICAST_FILTER_2
multicastAddress | 6-byte address (all 0xFF will inactivate the filter)
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_SetMultiCastFilter Function


WF_SetRegionalDomain Function

Contents | Index | Home
Previous | Up | Next
WF_SetRegionalDomain Function
C
void WF_SetRegionalDomain(
    UINT8 regionalDomain
);
Description

see tWFRegDomain enumerated types

Sets the regional domain on the MRF24WB0M. Note that this function does not overwrite the factory-set regional domain in FLASH. By default the MRF24WB0M will use the factory-set regional domain. It is invalid to call this function while in a connected state.

Valid values for the regional domain are:

  • WF_DOMAIN_FCC
  • WF_DOMAIN_IC
  • WF_DOMAIN_ETSI
  • WF_DOMAIN_SPAIN
  • WF_DOMAIN_FRANCE
  • WF_DOMAIN_JAPAN_A
  • WF_DOMAIN_JAPAN_B
Preconditions

MACInit must be called first. This function must not be called while in a connected state.

Parameters
Parameters | Description
regionalDomain | Value to set the regional domain to
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_SetRegionalDomain Function


WF_SetRtsThreshold Function

Contents | Index | Home
Previous | Up | Next
WF_SetRtsThreshold Function
C
void WF_SetRtsThreshold(
    UINT16 rtsThreshold
);
Description

RTS Threshold Functions

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 WF_RTS_THRESHOLD_MAX (2347).

Preconditions

MACInit must be called first.

Parameters
Parameters | Description
rtsThreshold | Value of the packet size threshold
Returns

None.

Remarks

None.

Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WF_SetRtsThreshold Function


tWFDeviceInfoStruct Structure

Contents | Index | Home
Previous | Up | Next
tWFDeviceInfoStruct Structure
C
struct tWFDeviceInfoStruct {
  UINT8 deviceType;
  UINT8 romVersion;
  UINT8 patchVersion;
};
Description

used in WF_GetDeviceInfo

Members
Members | Description
UINT8 deviceType; | MRF24WB0M_DEVICE_TYPE
UINT8 romVersion; | ROM version number
UINT8 patchVersion; | Patch version number
Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > tWFDeviceInfoStruct Structure


WFMacStatsStruct Structure

Contents | Index | Home
Previous | Up | Next
WFMacStatsStruct Structure
C
struct WFMacStatsStruct {
  UINT32 MibWEPExcludeCtr;
  UINT32 MibTxBytesCtr;
  UINT32 MibTxMulticastCtr;
  UINT32 MibTxFailedCtr;
  UINT32 MibTxRtryCtr;
  UINT32 MibTxMultRtryCtr;
  UINT32 MibTxSuccessCtr;
  UINT32 MibRxDupCtr;
  UINT32 MibRxCtsSuccCtr;
  UINT32 MibRxCtsFailCtr;
  UINT32 MibRxAckFailCtr;
  UINT32 MibRxBytesCtr;
  UINT32 MibRxFragCtr;
  UINT32 MibRxMultCtr;
  UINT32 MibRxFCSErrCtr;
  UINT32 MibRxWEPUndecryptCtr;
  UINT32 MibRxFragAgedCtr;
  UINT32 MibRxMICFailureCtr;
};
Description

This is record WFMacStatsStruct.

Members
Members | Description
UINT32 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 MibTxBytesCtr; | Total number of Tx bytes that have been transmitted
UINT32 MibTxMulticastCtr; | Number of frames successfully transmitted that had the multicast bit set in the destination MAC address.
UINT32 MibTxFailedCtr; | Number of Tx frames that failed due to the number of transmits exceeding the retry count.
UINT32 MibTxRtryCtr; | Number of times a transmitted frame needed to be retried
UINT32 MibTxMultRtryCtr; | Number of times a frame was successfully transmitted after more than one retransmission.
UINT32 MibTxSuccessCtr; | Number of Tx frames successfully transmitted.
UINT32 MibRxDupCtr; | Number of frames received where the Sequence Control field indicates a duplicate.
UINT32 MibRxCtsSuccCtr; | Number of CTS frames received in response to an RTS frame.
UINT32 MibRxCtsFailCtr; | Number of times an RTS frame was not received in response to a CTS frame.
UINT32 MibRxAckFailCtr; | Number of times an Ack was not received in response to a Tx frame.
UINT32 MibRxBytesCtr; | Total number of Rx bytes received.
UINT32 MibRxFragCtr; | Number of successful received frames (management or data)
UINT32 MibRxMultCtr; | Number of frames received with the multicast bit set in the destination MAC address.
UINT32 MibRxFCSErrCtr; | Number of frames received with an invalid Frame Checksum (FCS).
UINT32 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 MibRxFragAgedCtr; | Number of times that fragments ‘aged out’, or were not received in the allowable time.
UINT32 MibRxMICFailureCtr; | Number of MIC failures that have occurred.
Wi-Fi API > Wi-Fi Miscellaneous > Wi-Fi Miscellaneous Public Members > WFMacStatsStruct Structure


WF_ProcessEvent

Contents | Index | Home
Previous | Up | Next
WF_ProcessEvent

There are several events that can occur on the MRF24WB0M that the host CPU may want to know about. All MRF24WB0M events go through the WF_ProcessEvent() function described in the next section.

Event Processing

The WF_ProcessEvent() function is how the host application is notified of events. This function will be called by the Wi-Fi host driver when an event occurs. This function should not be called directly by the host application. This function, located in WF_Customize.c, should be modified by the user as needed. Since this function is called from the WiFi driver there are some restrictions – namely, one cannot call any Wi-Fi driver functions when inside WFProcessEvent. It is recommended that that customer simply set a flag for a specific event and handle it in the main loop. The framework for this function is shown below.

The prototype for this function is:

UINT16 WF_ProcessEvent(UINT8 event, UINT16 eventinfo);

There are two inputs to the function:

event | The event that occurred.
eventInfo | Additional information about the event. This is not applicable to all events.

The table below shows possible values that the event and eventInfo parameters can have. Note that event notification of some events can be optionally disabled via:

  1. Bit mask eventNotificationAction in the tWFCAElements structure (see Wi-Fi Connection Algorithm), or
  2. Function WF_CASetEventNotificationAction().

event
eventInfo
WF_EVENT_CONNECTION_SUCCESSFUL
The connection attempt was successful.
eventInfo:

  • Always WF_NO_ADDITIONAL_INFO

(Optional event)

WF_EVENT_CONNECTION_FAILED
The connection attempt failed
eventInfo:

  • WF_JOIN_FAILURE
  • WF_AUTHENTICATION_FAILURE
  • WF_ASSOCIATION_FAILURE
  • WF_WEP_HANDSHAKE_FAILURE
  • WF_PSK_CALCULATION_FAILURE
  • WF_PSK_HANDSHAKE_FAILURE
  • WF_ADHOC_JOIN_FAILURE
  • WF_SECURITY_MISMATCH_FAILURE
  • WF_NO_SUITABLE_AP_FOUND_FAILURE
  • WF_RETRY_FOREVER_NOT_SUPPORTED_FAILURE

(Optional event)

WF_EVENT_CONNECTION_TEMPORARILY_LOST
An established connection was temporarily lost – the connection algorithm is attempting to reconnect. The eventInfo field indicates why the connection was lost.
eventInfo:

  • WF_BEACON_TIMEOUT
  • WF_DEAUTH_RECEIVED
  • WF_DISASSOCIATE_RECEIVED

(Optional event)

WF_EVENT_CONNECTION_PERMANENTLY_LOST
An established connection was permanently lost – the connection algorithm either ran out of retries or was configured not to retry. The eventInfo field indicates why the connection was lost.
eventInfo:

  • WF_BEACON_TIMEOUT
  • WF_DEAUTH_RECEIVED
  • WF_DISASSOCIATE_RECEIVED

This event can also be generated when WF_CMDisconnect() is called, in which case the eventInfo field has no meaning.

(Optional event)

WF_EVENT_CONNECTION_REESTABLISHED
A connection that was temporarily lost has been restablished
Always WF_NO_ADDITIONAL_INFO
(Optional event)
WF_EVENT_SCAN_RESULTS_READY
The scan request initiated by calling WF_Scan() has completed and results can be read from the MRF24WB0M.
eventInfo: Number of scan results
12.2 WF_ProcessEvent() Framework

Below is the framework for WF_ProcessEvent(). Each case statement should be modified as needed to handle events the application is interested in.

Copy Code
void WF_ProcessEvent(UINT8 event, UINT16 eventInfo)
{
    switch (event)
    {
        case WF_EVENT_CONNECTION_SUCCESSFUL:
            /* Application code here */
            break;

        case WF_EVENT_CONNECTION_FAILED:
            /* Application code here */
            break;

        case WF_EVENT_CONNECTION_TEMPORARILY_LOST:
           /* Application code here */
            break;

        case WF_EVENT_CONNECTION_PERMANENTLY_LOST:
           /* Application code here */
            break;

        case WF_EVENT_FLASH_UPDATE_SUCCESSFUL:
           /* Application code here */
            break;

        case WF_EVENT_FLASH_UPDATE_FAILED:
           /* Application code here */
            break;

        case WF_EVENT_KEY_CALCULATION_COMPLETE:
           /* Application code here */
            break;

        case WF_EVENT_SCAN_RESULTS_READY:
           /* Application code here */
            break;

        case WF_EVENT_IE_RESULTS_READY:
           /* Application code here */
            break;

        default:
            WF_ASSERT(FALSE);
          break;
    }
}
Module

Wi-Fi API

Wi-Fi API > WF_ProcessEvent


Access Point Compatibility

Contents | Index | Home
Previous | Up | Next
Access Point Compatibility
Introduction

The MRF24WB0M has passed through Wi-Fi.org certification testing. Not all routers pass through Wi-Fi.org certification, and some are pre-configured in Greenfield modes. Further, users can set configurations that severely limit performance or prevent communications. This app note is intended to provide an on-going compatibility snapshot among a few of the most popular and market leading access points as well as a larger group of worldwide units. The test results will show the usability of the Microchip Wi-Fi modules operating with the latest release of the Microchip TCPIP stack.

Wi-Fi Alliance Testing

To carry the Wi-Fi Alliance logo, Wi-Fi products must successfully pass numerous tests, including compatibility testing. Wi-Fi compatibility testing is performed against 4 representative access points, with a subset of tests run against each of the access points. Devices are tested against these access points for characteristics such as connectivity, security, throughput, and a breadth of other specifications. Microchip Wi-Fi modules have successfully passed the Wi-Fi Alliance testing. The report is titled WFA7150 and is available at [image] http://certifications.wi-fi.org/pdf_certificate.php?cid=WFA7150

Additional Wi-Fi Compatibility Testing

Wi-Fi technology is dramatically expanding the reach and applications of the internet to embedded devices. In many cases, Wi-Fi is new to the markets and applications it is reaching. As a result, Microchip feels it is important to raise the bar on compatibility testing, and education of the developer.

Microchip has thus adopted the Wi-Fi.org test bench for more generic Access Point testing. The goal of these tests is to ensure basic connectivity in multiple non-secure and secure scenarios with a global representation of top selling access points.

Pass Criteria

The following tests are part of the current testing suite and must pass for the Access Point to be considered compatible.

• Following in conditions of no security, WEP40 and WEP104, WPA-PSK (TKIP), WPA2-PSK (AES)

• AP association, Iperf UDP upload/download, Iperf TCP upload/download, DHCP, ICMP ping

In many cases there are other modes that can be run with the Access Points and the user must take caution that if the mode is not listed, then compatibility is not necessarily guaranteed. These modes are usually Greenfield use, modes being deprecated by Wi-Fi.org, or cases of limiting the use of the Access Point for more private networking purposes and not for true Wi-Fi compatibility.

Examples of special modes not necessarily part of the results:

• WPA-PSK(AES) security: WPA-PSK security is defined as using TKIP. This is a mixed mode. This mode works if the AP just auto-detects and does not mix.

• WPA2-PSK (TKIP) security: WPA2-PSK security is defined as using 802.11i with AES. This is a mixed mode. This mode works if the AP just auto-detects and does not mix.

• 802.11g only, 802.11n only, 802.11g/n only: these are private network modes (cutting out mandatory support for 802.11b). These modes may work if basic rates are limited to 1&2mbps per 802.11.

List of compatible Access Points:
  • 2Wire 1701HG
  • 2Wire 2701HG-B
  • 3COM 3CRWER100-75
  • 3COM WL-524
  • Actiontec GT704-WG
  • AirLink AR690W
  • Belkin N1
  • Belkin F5D7231-4
  • Buffalo WHR-G125
  • Buffalo WHR-HP-G54
  • Corega CG-WLAPGMN
  • Corega CG-WLBARGO
  • D-Link DIR-655
  • D-Link WBR-1310
  • Dynex DX-WGRTR
  • Level1 WBR-3408
  • Linksys WRT150Nv1.1
  • Linksys WRT310N
  • Microsoft MN-700
  • Netgear WGR614v9
  • Netgear WGT624v3
  • Netgear WNDR3300
  • Netgear WPN824v2
  • Proxim AP-700
  • SMC Networks SMCWBR14T-G
  • TP-Link TL-WR541G
  • Westell B90-327W15-06

*Note Tests Performed:

• Basic association with the AP (no security)

• Association with WEP security

• Association with WPA/WPA2-PSK security

• Ping test validation.

Module

Wi-Fi API

Wi-Fi API > Access Point Compatibility


WiFi Tips and Tricks

Contents | Index | Home
Previous | Up | Next
WiFi Tips and Tricks
Tips for Setting up Routers for 802.11b Use

The purpose of this section is to describe the settings for the most typical AP configurable parameters to enable compatibility with the Microchip MRF24WB0Mx devices :

  1. DHCP Settings - For DHCP on LAN side (where AP is DHCP server), set Router to Enable DHCP server. Set Client Lease time to be longer than the typical off time of the station to ensure that the IP address provided doesn’t change each time the station is powered up. If an option for Always Broadcast is present for DHCP setup (broadcasts all DHCP responses to all clients), it should be disabled.
  2. Data Rate Settings - Ensure that service rates include 802.11b. 802.11g or 802.11n only rates (green field) should be avoided, but mixed settings are usually acceptable. If a Basic Rate setting is defined, it should be set to 1 and 2MBPS only.
  3. SSID Broadcast - Should typically be enabled so that the AP sends beacon frames containing the SSID. If disabled, ensure that Microchip Stack is set for Active Scanning.
  4. Channel Selection - For debug purposes, it is typical to use a fixed channel instead of Auto Channel Selection. If a fixed channel has been selected for the MRF24 Station, select the corresponding channel for the AP.
  5. Multicast Passthrough - If using multicast features (ZeroConfig for instance) ensure that the Router is configured to enable forwarding of Multicast packets.
  6. Beacon Interval - Set the value for the time interval between AP beacons, typical is 100msec. For lower power, this can be set to a smaller value, say 30mS, if the DTIM interval is correspondingly increased.
  7. RTS Threshold - Set the value for the frame size above which RTS/CTS will be used, typical is 2347.
  8. Fragmentation Threshold - Set the value for the frame size above which packets will be fragmented, typical is 2346.
  9. DTIM Interval - Set the value for Delivery Traffic Indication Message Interval, typical is 3 if the Beacon Interval is set for 100mSec. For lower power with the MRF24WB0M, if the Beacon Interval is set to 30mS, then the DTIM should be set to 100 to allow 300mS DTIM Interval.
  10. WLAN Partition (or AP Isolation)- Prevents AP clients from communicating to each other, typically disabled.
  11. WMM Enable - Allows wireless multimedia traffic, disable unless necessary for other AP services.
  12. Short Guard Interval (GI) - Lowers the guard interval between frames, disable unless necessary for other AP services.
  13. WiFi Protected Setup (WPS) - Enables WPS device discovery, disable unless necessary for other AP services.
  14. Frame Burst - Enables higher wireless packet throughput, disable unless necessary for other AP services. This may be called turbo, or other marketing terms.
  15. CTS Protection Mode – Improves reliability of 802.11g traffic, disable unless necessary for other AP services.
  16. Key Entry – Security can be entered with either a numerical key or an ASCII passphrase. Ensure you enter what the AP expects. If just starting, it is best to have another station like a laptop to validate what the AP is expecting.
Module

Wi-Fi API

Wi-Fi API > WiFi Tips and Tricks


Hot Topics

Contents | Index | Home
Previous | Up
Hot Topics

Host Controlled Connection Manager Clarifications

The following clarifications are to be noted for use of the device with Microchip TCPIP Stack versions unless otherwise noted.

1. Null String ESSID

It is possible to call WF_CMConnect(cpId) with a cpId of zero. If this happens, the connection manager can use erroneous values for the SSID, Network Mode, Security configuration, etc. which will cause the module to connect to a wrong AP or not connect at all. The only valid values that can be used for connection profile references are 1 and 2 (assuming that the WF_CPCreate(&cpId) succeeded in creating these profile references prior to the attempted connection).

Work around:

When creating a connection profile, verify that the profile number returned is always either 1 or 2. If the returned value is 0, delete the profile and recreate it. When connecting with WF_CMConnect(cpId), ensure that only a valid profile number previously returned from WF_CPCreate(&cpId) is used.

2. Management scan message conflict

Management messages must always return successful or it causes an assert in the host driver. An unsuccessful management message can occur when the connection retry is enabled (MY_DEFAULT_LIST_RETRY_COUNT>0) causing the device to be scanning due to a dropped connection, and then a disconnect, or connect, or scan command is sent.

Work around:

If you are controlling connect/reconnect from the host actively, then disable all firmware retry by using “no scan retry” and “no de-authorization action”.

a. To disable Scan Retry

WF_CASetListRetryCount(MY_DEFAULT_LIST_RETRY_COUNT); should be 0

b. To disable De-authorization action

WF_CASetDeauthAction(WF_DO_NOT_ATTEMPT_TO_RECONNECT);

c. To disable De-authentication action

WF_CASetBeaconTimeoutAction(WF DO NOT ATTEMPT TO RECONNECT);

d. Use “Connect” only on “permanent loss” or “connection failure”.

e. To do a Scan, first check the firmware state first by using WF_CMGetConnectionState()

i. If the return state is WF_CSTATE_NOT_CONNECTED (or WF_CSTATE_CONNECTION_PERMANENTLY_LOST), then this means firmware is in IDLE, so host can issue host scan safely

ii. If the return state is WF_CSTATE_CONNECTED_INFRASTRUCTURE, then this means firmware is in CONNECTED. In this case a scan command can be issued but a watchdog timer must be used to time for conflict. Also, ensure the management timer is set for at least 0.4seconds per channel scanned to prevent queued Tx buffer requests from timing out.

iii. If return state is WF_CSTATE_CONNECTION_IN_PROGRESS ( or WF_CSTATE_RECONNECTION_IN_PROGRESS), then this means firmware is in the middle of connection process and a scan must not be initiated.

f. If “Disconnect” function is desired, a watchdog timer needs to be used to address the case where a conflict occurs with an over the air disassociate or deauthorize.

g. For watchdog timing, advised timing is 2x the management packet timeout (that is, use 4seconds unless the management timeout has been increased).

b. If you are only using the firmware retry and not doing ANY connection management (scan, connect, idle, etc.) then you can use MY_DEFAULT_LIST_RETRY_COUNT>0 or retry forever (MY_DEFAULT_LIST_RETRY_COUNT=255). If you lose connection, you can reconnect using the “connect” API. Do not use “Disconnect”.

a. If “Disconnect” function is desired, a watchdog timer needs to be used to address the case where a conflict occurs with an over the air disassociate or deauthorize.

Module

Wi-Fi API

Wi-Fi API > Hot Topics


ARP Types

Contents | Index | Home
ARP Types
Types
Name | Description
ARP_PACKET | ARP packet structure
Stack API > ARP


Types (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Type
Stack API > ARP


Generic TCP Server Macros

Contents | Index | Home
Generic TCP Server Macros
Macros
Name | Description
SERVER_PORT | Defines which port the server will listen on
Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Server


Macros (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Macro
Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Server


Helpers Functions

Contents | Index | Home
Helpers Functions
Functions
Name | Description
LFSRRand | Returns a pseudo-random 16-bit unsigned integer in the range from 0 to 65535 (0x0000 to 0xFFFF).
LFSRSeedRand | Seeds the LFSR random number generator invoked by the LFSRRand() function. The prior seed is returned.
Stack API > Helpers


Functions (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Method
Stack API > Helpers


Helpers Variables

Contents | Index | Home
Helpers Variables
Variables
Name | Description
dwLFSRRandSeed | Default Random Number Generator seed. 0x41FE9F9E corresponds to calling LFSRSeedRand(1)
Stack API > Helpers


Variables (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Variable
Stack API > Helpers


Network Management (SNMP) Server Functions

Contents | Index | Home
Network Management (SNMP) Server Functions
Functions
Name | Description
SendNotification | Prepare, validate remote node which will receive trap and send trap pdu.
SNMPGetTimeStamp | Obtains the current Tick value for the SNMP time stamp.
Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server


Functions (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Method
Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server


Network Management (SNMP) Server Macros

Contents | Index | Home
Network Management (SNMP) Server Macros
Macros
Name | Description
MAX_TRY_TO_SEND_TRAP |
SNMP_MAX_NON_REC_ID_OID | Update the Non record id OID value which is part of CustomSnmpDemo.c file
STACK_USE_SMIV2 | Default STACK_USE_SMIV2 is enabled . For Stack V5.31, STACK_USE_SMIV2 should be disabled.
Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server


Macros (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Macro
Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server


Network Management (SNMP) Server Variables

Contents | Index | Home
Network Management (SNMP) Server Variables
Variables
Name | Description
gSendTrapSMstate | This is variable gSendTrapSMstate.
gSnmpNonMibRecInfo | OLD snmp.mib file with SMIv1 standard
gSnmpv3UserSecurityName | This is variable gSnmpv3UserSecurityName.
Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server


Variables (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Variable
Demo Information > Available Demos > Demo App > Demo Modules > Network Management (SNMP) Server


SNMP Functions

Contents | Index | Home
SNMP Functions
Functions
Name | Description
getSnmpV2GenTrapOid | Resolves generic trap code to generic trap OID.
ProcessGetBulkVar | This is function ProcessGetBulkVar.
ProcessGetNextVar | This is function ProcessGetNextVar.
ProcessGetVar | This is function ProcessGetVar.
ProcessSnmpv3MsgData | This is function ProcessSnmpv3MsgData.
SNMPGetExactIndex | To search for exact index node in case of a Sequence variable.
SNMPIdRecrdValidation | Used to Restrict the access dynamic and non dynamic OID string for A perticular SNMP Version.
SNMPIsValidSetLen | Validates the set variable data length to data type.
Snmpv3AESDecryptRxedScopedPdu | This is function Snmpv3AESDecryptRxedScopedPdu.
Snmpv3BufferPut | This is function Snmpv3BufferPut.
Snmpv3FormulateEngineID | This is function Snmpv3FormulateEngineID.
Snmpv3GetAuthEngineTime | This is function Snmpv3GetAuthEngineTime.
Snmpv3GetBufferData | This is function Snmpv3GetBufferData.
Snmpv3InitializeUserDataBase | This is function Snmpv3InitializeUserDataBase.
Snmpv3MsgProcessingModelProcessPDU | This is function Snmpv3MsgProcessingModelProcessPDU.
Snmpv3Notify | This is function Snmpv3Notify.
Snmpv3ScopedPduProcessing | This is function Snmpv3ScopedPduProcessing.
Snmpv3TrapScopedpdu | This is function Snmpv3TrapScopedpdu.
Snmpv3UserSecurityModelProcessPDU | This is function Snmpv3UserSecurityModelProcessPDU.
Snmpv3UsmAesEncryptDecryptInitVector | This is function Snmpv3UsmAesEncryptDecryptInitVector.
Snmpv3UsmOutMsgAuthenticationParam | This is function Snmpv3UsmOutMsgAuthenticationParam.
Snmpv3ValidateEngineId | This is function Snmpv3ValidateEngineId.
Snmpv3ValidateSecNameAndSecLvl | This is function Snmpv3ValidateSecNameAndSecLvl.
Snmpv3ValidateSecurityName | This is function Snmpv3ValidateSecurityName.
Stack API > SNMP


Functions (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Method
Stack API > SNMP


SNMP Macros

Contents | Index | Home
SNMP Macros
Macros
Name | Description
IS_SNMPV3_AUTH_STRUCTURE | This is macro IS_SNMPV3_AUTH_STRUCTURE.
REPORT_RESPONSE | This is macro REPORT_RESPONSE.
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_V3 | This is macro SNMP_V3.
Stack API > SNMP


Macros (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Macro
Stack API > SNMP


SNMP Types

Contents | Index | Home
SNMP Types
Types
Name | Description
INOUT_SNMP_PDU | This is type INOUT_SNMP_PDU.
SNMPNONMIBRECDINFO | This is type SNMPNONMIBRECDINFO.
SNMPV3MSGDATA | SNMPv3
Stack API > SNMP


Types (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Type
Stack API > SNMP


SNMP Variables

Contents | Index | Home
SNMP Variables
Variables
Name | Description
getZeroInstance | This variable is used for gext next request for zero instance
gSNMPv3ScopedPduDataPos | This is variable gSNMPv3ScopedPduDataPos.
gSNMPv3ScopedPduRequestBuf | This is variable gSNMPv3ScopedPduRequestBuf.
gSNMPv3ScopedPduResponseBuf | This is variable gSNMPv3ScopedPduResponseBuf.
msgSecrtyParamLenOffset | This is variable msgSecrtyParamLenOffset.
Stack API > SNMP


Variables (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Variable
Stack API > SNMP


TCP Variables

Contents | Index | Home
TCP Variables
Variables
Name | Description
NextPort | Tracking variable for next local client port number
Stack API > TCP


Variables (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Variable
Stack API > TCP


Web Page Demos Functions

Contents | Index | Home
Web Page Demos Functions
Functions
Name | Description
HTTPPostSNMPCommunity | This is function HTTPPostSNMPCommunity.
HTTPPostConfig | Processes the configuration form on config/index.htm
HTTPPostDDNSConfig | Parsing and collecting http data received from http form.
HTTPPostEmail | Processes the e-mail form on email/index.htm
HTTPPostLCD | Processes the LCD form on forms.htm
HTTPPostMD5 | Processes the file upload form on upload.htm
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos


Functions (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Method
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos


Web Page Demos Variables

Contents | Index | Home
Web Page Demos Variables
Variables
Name | Description
DDNSData | RAM allocated for DDNS parameters
lastFailure | Stick status message variable. See lastSuccess for details.
lastSuccess | Sticky status message variable. This is used to indicated whether or not the previous POST operation was successful. The application uses these to store status messages when a POST operation redirects. This lets the application provide status messages after a redirect, when connection instance data has already been lost.
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos


Variables (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Variable
Demo Information > Available Demos > Demo App > Demo Modules > Web Page Demos


Generic TCP Client Variables

Contents | Index | Home
Generic TCP Client Variables
Variables
Name | Description
RemoteURL | Defines the URL to be requested by this HTTP client
ServerName | Defines the server to be accessed for this application
ServerPort | Defines the port to be accessed for this application
Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Client


Variables (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Variable
Demo Information > Available Demos > Demo App > Demo Modules > Generic TCP Client


Ping (ICMP) Demo Macros

Contents | Index | Home
Ping (ICMP) Demo Macros
Macros
Name | Description
HOST_TO_PING | Address that ICMP client will ping. If the DNS client module is not available in the stack, then this hostname is ignored and the local gateway IP address will be pinged instead.
Demo Information > Available Demos > Demo App > Demo Modules > Ping (ICMP) Demo


Macros (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Macro
Demo Information > Available Demos > Demo App > Demo Modules > Ping (ICMP) Demo


UDP Types

Contents | Index | Home
UDP Types
Types
Name | Description
UDP_STATE | UDP States
Stack API > UDP


Types (AutoDoc Folder)

Contents | Index | Home
Legend
Legend
Type
Stack API > UDP


Contents

Contents | Index | Home
Contents
This is the table of contents of this documentation.
Introduction
Getting Help
Directory Structure
SW License Agreement
Release Notes
Stack Performance
Memory Usage
Peripheral Usage
Silicon Solutions
Software
TCP/IP Configuration Wizard
MPFS2 Utility
Building MPFS2 Images
Uploading Pre-built MPFS2 Images
Advanced MPFS2 Settings
MPFS2 Command Line Options
Hash Table Filter Entry Calculator
Microchip TCP/IP Discoverer
Getting Started
Hardware Setup
Daughter Boards
PICDEM.net 2
PIC18 Explorer
Explorer 16 and PIC32 Starter Kit
PIC24FJ256DA210 Dev Board
Programming and First Run
Configure your WiFi Access Point
Connecting to the Network
Uploading Web Pages
Accessing the Demo Application
Configuring WiFi Security
Demo Information
Demo Compatibility Table
Available Demos
Demo App
TCPIP Demo App Features by Hardware Platform
Demo Modules
Web Page Demos
Dynamic Variables
Authentication
Forms using GET
Forms using POST
Cookies
Functions
HTTPPostSNMPCommunity Function
HTTPPostConfig Function
HTTPPostDDNSConfig Function
HTTPPostEmail Function
HTTPPostLCD Function
HTTPPostMD5 Function
Variables
DDNSData Variable
lastFailure Variable
lastSuccess Variable
E-mail (SMTP) Demo
SMTPDemo Function
Generic TCP Client
GenericTCPClient Function
Variables
RemoteURL Variable
ServerName Variable
ServerPort Variable
Generic TCP Server
GenericTCPServer Function
Macros
SERVER_PORT Macro
Ping (ICMP) Demo
PingDemo Function
Macros
HOST_TO_PING Macro
Network Management (SNMP) Server
MIB files
MIB Browsers
SNMP Operations
SNMP Traps
HTTP Configuration
Functions
SendNotification Function
SNMPGetTimeStamp Function
Variables
gSendTrapSMstate Variable
gSnmpNonMibRecInfo Variable
gSnmpv3UserSecurityName Variable
Macros
MAX_TRY_TO_SEND_TRAP Macro
SNMP_MAX_NON_REC_ID_OID Macro
STACK_USE_SMIV2 Macro
UART-to-TCP Bridge
Zero Configuration (ZeroConf)
Internet Bootloader
Bootloader Design
Using the Bootloader
WebVend
Internet Radio
WiFi Console
Standalone Commands
iwconfig Commands
ifconfig Commands
iwpriv Commands
iperf Example
WiFi EZConfig
Demo App MDD
Google PowerMeter
Energy Monitoring
Using the Stack
Stack Architecture
How the Stack Works
Required Files
APP_CONFIG Structure
Main File
Initialization
Main Loop
Cooperative Multitasking
RTOS
Configuring the Stack
Hardware Configuration
Clock Frequency
External Storage
ENC28J60 Config
ENCX24J600 Config
PIC18F97J60 Config
PIC32MX7XX Config
Address
MAC Address
IP Address
Protocol Configuration
Protocol Macros and Files
Additional Features
Sockets
Memory Allocation
Socket Types
Initialization Structure
UDP Sockets
BSD Sockets
Stack API
Announce
Stack Members
AnnounceIP Function
DiscoveryTask Function
ARP
Public Members
ARPResolve Function
ARPIsResolved Function
ARPDeRegisterCallbacks Function
ARPRegisterCallbacks Function
ARPSendPkt Function
arp_app_callbacks Structure
ARP_REQ Macro
ARP_RESP Macro
MAX_REG_APPS Macro
Stack Members
ARPInit Function
ARPProcess Function
Internal Members
ARPPut Function
SwapARPPacket Function
ARP_OPERATION_REQ Macro
ARP_OPERATION_RESP Macro
HW_ETHERNET Macro
ARP_IP Macro
Cache Variable
reg_apps Variable
Types
ARP_PACKET Structure
BSD Sockets
Public Members
accept Function
AF_INET Macro
bind Function
BSDSocket Structure
closesocket Function
connect Function
gethostname Function
in_addr Structure
INADDR_ANY Macro
INVALID_TCP_PORT Macro
IP_ADDR_ANY Macro
IPPROTO_IP Macro
IPPROTO_TCP Macro
IPPROTO_UDP Macro
listen Function
recv Function
recvfrom Function
send Function
sendto Function
SOCK_DGRAM Macro
SOCK_STREAM Macro
sockaddr Structure
SOCKADDR Type
sockaddr_in Structure
SOCKADDR_IN Type
socket Function
SOCKET Type
SOCKET_CNXN_IN_PROGRESS Macro
SOCKET_DISCONNECTED Macro
SOCKET_ERROR Macro
Stack Members
BerkeleySocketInit Function
Internal Members
BSD_SCK_STATE Enumeration
BSDSocketArray Variable
gAutoPortNumber Variable
HandlePossibleTCPDisconnection Function
DNS
Public Members
DNSBeginUsage Function
DNSEndUsage Function
DNSResolve Function
DNSResolveROM Function
DNSIsResolved Function
DNS_TYPE_A Macro
DNS_TYPE_MX Macro
Internal Members
DNSPutString Function
DNSPutROMString Function
DNS_PORT Macro
DNS_TIMEOUT Macro
DNSHostName Variable
DNSHostNameROM Variable
Flags Variable
RecordType Variable
ResolvedInfo Variable
smDNS Variable
DNS_HEADER Structure
DNSDiscardName Function
Dynamic DNS Client
Public Members
DDNS_POINTERS Structure
DDNS_SERVICES Enumeration
DDNS_STATUS Enumeration
DDNSClient Variable
DDNSForceUpdate Function
DDNSGetLastIP Function
DDNSGetLastStatus Function
DDNSSetService Function
Stack Members
DDNSInit Function
DDNSTask Function
Internal Members
bForceUpdate Variable
ddnsServiceHosts Variable
ddnsServicePorts Variable
dwUpdateAt Variable
lastKnownIP Variable
lastStatus Variable
_checkIpSrvrResponse Variable
_updateIpSrvrResponse Variable
DDNS_CHECKIP_SERVER Macro
DDNS_DEFAULT_PORT Macro
Hashes
Public Members
HashAddData Function
HashAddROMData Function
MD5Calculate Function
MD5Initialize Function
SHA1Calculate Function
SHA1Initialize Function
HASH_SUM Structure
Stack Members
MD5AddROMData Function
SHA1AddROMData Function
SHA1AddData Function
MD5AddData Function
Internal Members
_MD5_k Variable
_MD5_r Variable
lastBlock Variable
HASH_TYPE Enumeration
SHA1HashBlock Function
MD5HashBlock Function
Helpers
Public Members
Base64Decode Function
Base64Encode Function
btohexa_high Function
btohexa_low Function
CalcIPBufferChecksum Function
CalcIPChecksum Function
ExtractURLFields Function
FormatNetBIOSName Function
GenerateRandomDWORD Function
hexatob Function
leftRotateDWORD Function
leftRotateDWORD Macro
Replace Function
ROMStringToIPAddress Function
ROMStringToIPAddress Macro
stricmppgm2ram Function
StringToIPAddress Function
strupr Function
strnchr Function
swapl Function
swaps Function
uitoa Function
ultoa Function
UnencodeURL Function
Functions
LFSRRand Function
LFSRSeedRand Function
Variables
dwLFSRRandSeed Variable
HTTP2 Server
Features
Dynamic Variables
Form Processing
Authentication
Cookies
Compression
Public Members
curHTTP Variable
HTTP_CONN Structure
HTTP_IO_RESULT Enumeration
HTTP_READ_STATUS Enumeration
HTTPCheckAuth Function
HTTPExecuteGet Function
HTTPExecutePost Function
HTTPGetArg Function
HTTPGetROMArg Function
HTTPNeedsAuth Function
HTTPPrint_varname Function
HTTPReadPostName Function
HTTPReadPostPair Macro
HTTPReadPostValue Function
HTTPURLDecode Function
sktHTTP Macro
Stack Members
HTTPInit Function
HTTPServer Function
Internal Members
curHTTPID Variable
HTTP_CACHE_LEN Macro
HTTP_FILE_TYPE Enumeration
HTTP_MAX_DATA_LEN Macro
HTTP_MAX_HEADER_LEN Macro
HTTP_MIN_CALLBACK_FREE Macro
HTTP_PORT Macro
HTTP_STATUS Enumeration
HTTP_STUB Structure
HTTP_TIMEOUT Macro
httpContentTypes Variable
httpFileExtensions Variable
HTTPHeaderParseAuthorization Function
HTTPHeaderParseContentLength Function
HTTPHeaderParseCookie Function
HTTPHeaderParseLookup Function
HTTPIncFile Function
HTTPLoadConn Function
HTTPMPFSUpload Function
HTTPProcess Function
HTTPReadTo Function
HTTPRequestHeaders Variable
HTTPResponseHeaders Variable
HTTPS_PORT Macro
HTTPSendFile Function
httpStubs Variable
SM_HTTP2 Enumeration
smHTTP Macro
RESERVED_HTTP_MEMORY Macro
ICMP
Public Members
ICMPBeginUsage Function
ICMPSendPing Function
ICMPSendPingToHost Function
ICMPSendPingToHostROM Function
ICMPGetReply Function
ICMPEndUsage Function
ICMPSendPingToHostROM Macro
Internal Members
ICMPProcess Function
ICMPFlags Variable
ICMP_PACKET Structure
ICMPState Variable
ICMP_TIMEOUT Macro
ICMPTimer Variable
StaticVars Variable
wICMPSequenceNumber Variable
MPFS2
Public Members
MPFS_HANDLE Type
MPFS_INVALID Macro
MPFS_INVALID_HANDLE Macro
MPFS_SEEK_MODE Enumeration
MPFSClose Function
MPFSFormat Function
MPFSGet Function
MPFSGetArray Function
MPFSGetBytesRem Function
MPFSGetEndAddr Function
MPFSGetFilename Function
MPFSGetFlags Function
MPFSGetID Function
MPFSGetLong Function
MPFSGetMicrotime Function
MPFSGetPosition Function
MPFSGetSize Function
MPFSGetStartAddr Function
MPFSGetTimestamp Function
MPFSOpen Function
MPFSOpenID Function
MPFSOpenROM Function
MPFSPutArray Function
MPFSSeek Function
MPFSPutEnd Function
Stack Members
MPFSInit Function
Internal Members
isMPFSLocked Variable
lastRead Variable
MAX_FILE_NAME_LEN Macro
MPFS_PTR Type
MPFS_STUB Structure
MPFS_WRITE_PAGE_SIZE Macro
MPFS2_FLAG_HASINDEX Macro
MPFS2_FLAG_ISZIPPED Macro
MPFSStubs Variable
MPFSTell Macro
ReadProgramMemory Function
_LoadFATRecord Function
_Validate Function
MPFS_FAT_RECORD Structure
fatCache Variable
fatCacheID Variable
numFiles Variable
MPFS_INVALID_FAT Macro
NBNS
Stack Members
NBNSGetName Function
NBNSPutName Function
NBNSTask Function
NBNS_HEADER Structure
NBNS_PORT Macro
Performance Tests
Stack Members
TCPPerformanceTask Function
UDPPerformanceTask Function
Internal Members
TCPRXPerformanceTask Function
TCPTXPerformanceTask Function
PERFORMANCE_PORT Macro
RX_PERFORMANCE_PORT Macro
TX_PERFORMANCE_PORT Macro
SMTP Client
Examples
Short Message
Long Message
Public Members
SMTP_CONNECT_ERROR Macro
SMTP_POINTERS Structure
SMTP_RESOLVE_ERROR Macro
SMTP_SUCCESS Macro
SMTPBeginUsage Function
SMTPClient Variable
SMTPEndUsage Function
SMTPFlush Function
SMTPIsBusy Function
SMTPIsPutReady Function
SMTPPut Function
SMTPPutArray Function
SMTPPutDone Function
SMTPPutROMArray Function
SMTPPutROMString Function
SMTPPutString Function
SMTPSendMail Function
Stack Members
SMTPTask Function
Internal Members
CRPeriod Variable
FindEmailAddress Function
FindROMEmailAddress Function
MySocket Variable
PutHeadersState Variable
ResponseCode Variable
RXParserState Variable
SMTP_PORT Macro
SMTP_SERVER_REPLY_TIMEOUT Macro
SMTPFlags Variable
SMTPServer Variable
SMTPState Variable
TransportState Variable
Reboot
Stack Members
RebootTask Function
REBOOT_PORT Macro
REBOOT_SAME_SUBNET_ONLY Macro
SNMP
Public Members
GENERIC_TRAP_NOTIFICATION_TYPE Enumeration
VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE Enumeration
SNMP_ACTION Enumeration
COMMUNITY_TYPE Enumeration
SNMP_VAL Union
TRAP_INFO Structure
gSendTrapFlag Variable
gSetTrapSendFlag Variable
gGenericTrapNotification Variable
gSpecificTrapNotification Variable
gOIDCorrespondingSnmpMibID Variable
SNMPSendTrap Function
SNMPValidateCommunity Function
SNMPNotify Function
SNMPSetVar Function
SNMPGetVar Function
SNMPIsNotifyReady Function
SNMPNotifyPrepare Function
SNMPGetNextIndex Function
SNMP_ID Type
SNMP_INDEX Type
SNMP_COMMUNITY_MAX_LEN Macro
OID_MAX_LEN Macro
SNMP_START_OF_VAR Macro
SNMP_END_OF_VAR Macro
SNMP_INDEX_INVALID Macro
TRAP_TABLE_SIZE Macro
TRAP_COMMUNITY_MAX_LEN Macro
NOTIFY_COMMUNITY_LEN Macro
Internal Members
_SNMPDuplexInit Function
_SNMPGet Function
_SNMPGetTxOffset Macro
_SNMPPut Function
_SNMPSetTxOffset Macro
AGENT_NOTIFY_PORT Macro
appendZeroToOID Variable
ASN_INT Macro
ASN_NULL Macro
ASN_OID Macro
DATA_TYPE Enumeration
DATA_TYPE_INFO Structure
DATA_TYPE_TABLE_SIZE Macro
dataTypeTable Variable
FindOIDsInRequest Function
GET_BULK_REQUEST Macro
GET_NEXT_REQUEST Macro
GET_REQUEST Macro
GET_RESPONSE Macro
hMPFS Variable
INDEX_INFO Union
IS_AGENT_PDU Macro
IS_ASN_INT Macro
IS_ASN_NULL Macro
IS_GET_NEXT_REQUEST Macro
IS_GET_REQUEST Macro
IS_GET_RESPONSE Macro
IS_OCTET_STRING Macro
IS_OID Macro
GetDataTypeInfo Function
IS_SET_REQUEST Macro
IS_STRUCTURE Macro
IS_TRAP Macro
IsASNNull Function
MIB_INFO Union
OCTET_STRING Macro
OID_INFO Structure
PDU_INFO Structure
reqVarErrStatus Structure
SET_REQUEST Macro
SetErrorStatus Function
SNMP_AGENT_PORT Macro
SNMP_BIB_FILE_NAME Macro
SNMP_COUNTER32 Macro
SNMP_ERR_STATUS Enumeration
SNMP_GAUGE32 Macro
SNMP_IP_ADDR Macro
SNMP_NMS_PORT Macro
SNMP_NOTIFY_INFO Structure
SNMP_NSAP_ADDR Macro
IsValidLength Function
SNMP_OPAQUE Macro
SNMP_STATUS Union
SNMP_TIME_TICKS Macro
SNMP_V1 Macro
SNMP_V2C Macro
SNMPAgentSocket Variable
SNMPNotifyInfo Variable
snmpReqVarErrStatus Variable
SNMPRxOffset Variable
SNMPStatus Variable
SNMPTxOffset Variable
STRUCTURE Macro
TRAP Macro
trapInfo Variable
GetDataTypeInfo Function
GetNextLeaf Function
GetOIDStringByAddr Function
GetOIDStringByID Function
IsValidCommunity Function
IsValidInt Function
IsValidLength Function
IsValidOID Function
IsValidPDU Function
IsValidStructure Function
OIDLookup Function
ProcessGetSetHeader Function
ProcessHeader Function
ProcessSetVar Function
ProcessVariables Function
ReadMIBRecord Function
SNMPCheckIfPvtMibObjRequested Function
Stack Members
SNMPInit Function
SNMPTask Function
Functions
getSnmpV2GenTrapOid Function
ProcessGetBulkVar Function
ProcessGetNextVar Function
ProcessGetVar Function
ProcessSnmpv3MsgData Function
SNMPGetExactIndex Function
SNMPIdRecrdValidation Function
SNMPIsValidSetLen Function
Snmpv3AESDecryptRxedScopedPdu Function
Snmpv3BufferPut Function
Snmpv3FormulateEngineID Function
Snmpv3GetAuthEngineTime Function
Snmpv3GetBufferData Function
Snmpv3InitializeUserDataBase Function
Snmpv3MsgProcessingModelProcessPDU Function
Snmpv3Notify Function
Snmpv3ScopedPduProcessing Function
Snmpv3TrapScopedpdu Function
Snmpv3UserSecurityModelProcessPDU Function
Snmpv3UsmAesEncryptDecryptInitVector Function
Snmpv3UsmOutMsgAuthenticationParam Function
Snmpv3ValidateEngineId Function
Snmpv3ValidateSecNameAndSecLvl Function
Snmpv3ValidateSecurityName Function
Types
INOUT_SNMP_PDU Enumeration
SNMPNONMIBRECDINFO Structure
SNMPV3MSGDATA Structure
Variables
getZeroInstance Variable
gSNMPv3ScopedPduDataPos Variable
gSNMPv3ScopedPduRequestBuf Variable
gSNMPv3ScopedPduResponseBuf Variable
msgSecrtyParamLenOffset Variable
Macros
IS_SNMPV3_AUTH_STRUCTURE Macro
REPORT_RESPONSE Macro
SNMP_MAX_MSG_SIZE Macro
SNMP_V3 Macro
SNTP Client
Public Members
SNTPGetUTCSeconds Function
Stack Members
SNTPClient Function
Internal Members
NTP_PACKET Structure
dwLastUpdateTick Variable
dwSNTPSeconds Variable
NTP_EPOCH Macro
NTP_FAST_QUERY_INTERVAL Macro
NTP_QUERY_INTERVAL Macro
NTP_REPLY_TIMEOUT Macro
NTP_SERVER Macro
NTP_SERVER_PORT Macro
SSL
Generating Server Certificates
Public Members
SSL_INVALID_ID Macro
TCPAddSSLListener Function
TCPSSLIsHandshaking Function
TCPStartSSLClient Function
TCPIsSSL Function
SSLStartSession Function
SSL_SUPPLEMENTARY_DATA_TYPES Enumeration
SSL_PKEY_INFO Structure
Stack Members
SSL_STATE Enumeration
SSLInit Function
SSLPeriodic Function
TCPRequestSSLMessage Function
TCPSSLGetPendingTxSize Function
TCPSSLHandleIncoming Function
TCPSSLHandshakeComplete Function
TCPSSLInPlaceMACEncrypt Function
TCPSSLPutRecordHeader Function
TCPStartSSLServer Function
SSL_MIN_SESSION_LIFETIME Macro
SSL_RSA_LIFETIME_EXTENSION Macro
Internal Members
CalculateFinishedHash Function
GenerateHashRounds Function
GenerateSessionKeys Function
HSEnd Function
HSGet Function
HSGetArray Function
HSGetWord Function
HSPut Function
HSPutArray Function
HSPutROMArray Function
HSPutWord Function
HSStart Function
isBufferUsed Variable
isHashUsed Variable
isStubUsed Variable
masks Variable
ptrHS Variable
RESERVED_SSL_MEMORY Macro
LoadOffChip Function
SaveOffChip Function
SM_SSL_RX_SERVER_HELLO Enumeration
SSL_ALERT Macro
SSL_ALERT_LEVEL Enumeration
SSL_APPLICATION Macro
SSL_BASE_BUFFER_ADDR Macro
SSL_BASE_HASH_ADDR Macro
SSL_BASE_KEYS_ADDR Macro
SSL_BASE_SESSION_ADDR Macro
SSL_BASE_STUB_ADDR Macro
SSL_BUFFER Union
SSL_BUFFER_SIZE Macro
SSL_BUFFER_SPACE Macro
SSL_CERT Variable
SSL_CERT_LEN Variable
SSL_CHANGE_CIPHER_SPEC Macro
SSL_HANDSHAKE Macro
SSL_HASH_SIZE Macro
SSL_HASH_SPACE Macro
SSL_KEYS Structure
SSL_KEYS_SIZE Macro
SSL_KEYS_SPACE Macro
SSL_MESSAGES Enumeration
SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 Macro
SSL_RSA_WITH_ARCFOUR_128_MD5 Macro
SSL_SESSION Structure
SSL_SESSION_SIZE Macro
SSL_SESSION_SPACE Macro
SSL_SESSION_STUB Structure
SSL_SESSION_TYPE Enumeration
SSL_STUB Structure
SSL_STUB_SIZE Macro
SSL_STUB_SPACE Macro
SSL_VERSION Macro
SSL_VERSION_HI Macro
SSL_VERSION_LO Macro
SSLBufferAlloc Function
SSLBufferFree Function
sslBufferID Variable
SSLBufferSync Function
SSLFinishPartialRecord Macro
SSLFlushPartialRecord Macro
sslHash Variable
SSLHashAlloc Function
SSLHashFree Function
sslHashID Variable
SSLHashSync Function
sslKeys Variable
sslKeysID Variable
SSLKeysSync Function
SSLMACAdd Function
SSLMACBegin Function
SSLMACCalc Function
SSLRSAOperation Function
sslRSAStubID Variable
SSLRxAlert Function
SSLRxAntiqueClientHello Function
SSLRxCCS Function
SSLRxClientHello Function
SSLRxClientKeyExchange Function
SSLRxFinished Function
SSLRxHandshake Function
SSLRxRecord Function
SSLRxServerCertificate Function
SSLRxServerHello Function
sslSession Variable
sslSessionID Variable
SSLSessionMatchID Function
SSLSessionMatchIP Function
SSLSessionNew Function
sslSessionStubs Variable
SSLSessionSync Function
SSLSessionUpdated Macro
sslSessionUpdated Variable
SSLStartPartialRecord Function
sslStub Variable
SSLStubAlloc Function
SSLStubFree Function
sslStubID Variable
SSLStubSync Function
SSLTerminate Function
SSLTxCCSFin Function
SSLTxClientHello Function
SSLTxClientKeyExchange Function
SSLTxMessage Function
SSLTxRecord Function
SSLTxServerCertificate Function
SSLTxServerHello Function
SSLTxServerHelloDone Function
TCP
Public Members
INVALID_SOCKET Macro
UNKNOWN_SOCKET Macro
TCP_ADJUST_GIVE_REST_TO_RX Macro
TCP_ADJUST_GIVE_REST_TO_TX Macro
TCP_ADJUST_PRESERVE_RX Macro
TCP_ADJUST_PRESERVE_TX Macro
TCP_OPEN_IP_ADDRESS Macro
TCP_OPEN_NODE_INFO Macro
TCP_OPEN_RAM_HOST Macro
TCP_OPEN_ROM_HOST Macro
TCP_OPEN_SERVER Macro
TCPAdjustFIFOSize Function
TCPConnect Macro
TCPClose Function
TCPDiscard Function
TCPDisconnect Function
TCPFind Macro
TCPFindArray Macro
TCPFindArrayEx Function
TCPFindEx Function
TCPFindROMArray Macro
TCPFindROMArrayEx Function
TCPFlush Function
TCPGet Function
TCPGetArray Function
TCPGetRemoteInfo Function
TCPGetRxFIFOFree Function
TCPGetRxFIFOFull Macro
TCPGetTxFIFOFree Macro
TCPGetTxFIFOFull Function
TCPIsConnected Function
TCPIsGetReady Function
TCPIsPutReady Function
TCPListen Macro
TCPOpen Function
TCPPeek Function
TCPPeekArray Function
TCPPut Function
TCPPutArray Function
TCPPutROMArray Function
TCPPutROMString Function
TCPPutString Function
TCPRAMCopy Function
TCPRAMCopyROM Function
TCPWasReset Function
Stack Members
SOCKET_INFO Structure
TCB Structure
TCB_STUB Structure
TCP_SOCKET Type
TCP_STATE Enumeration
TCPInit Function
TCPProcess Function
TCPTick Function
TCPSSLDecryptMAC Function
TCPStartSSLClientEx Function
Internal Members
ACK Macro
CloseSocket Function
FIN Macro
FindMatchingSocket Function
HandleTCPSeg Function
hCurrentTCP Variable
LOCAL_PORT_END_NUMBER Macro
LOCAL_PORT_START_NUMBER Macro
MyTCB Variable
MyTCBStub Variable
PSH Macro
RST Macro
SendTCP Function
SENDTCP_KEEP_ALIVE Macro
SENDTCP_RESET_TIMERS Macro
SwapTCPHeader Function
SYN Macro
SyncTCB Function
SyncTCBStub Macro
SYNQueue Variable
TCBStubs Variable
TCP_AUTO_TRANSMIT_TIMEOUT_VAL Macro
TCP_WINDOW_UPDATE_TIMEOUT_VAL Macro
TCP_CLOSE_WAIT_TIMEOUT Macro
TCP_DELAYED_ACK_TIMEOUT Macro
TCP_FIN_WAIT_2_TIMEOUT Macro
TCP_HEADER Structure
TCP_KEEP_ALIVE_TIMEOUT Macro
TCP_MAX_RETRIES Macro
TCP_MAX_SEG_SIZE_RX Macro
TCP_MAX_SEG_SIZE_TX Macro
TCP_MAX_SYN_RETRIES Macro
TCP_MAX_UNACKED_KEEP_ALIVES Macro
TCP_OPTIMIZE_FOR_SIZE Macro
TCP_OPTIONS Structure
TCP_OPTIONS_END_OF_LIST Macro
TCP_OPTIONS_MAX_SEG_SIZE Macro
TCP_OPTIONS_NO_OP Macro
TCP_SOCKET_COUNT Macro
TCP_START_TIMEOUT_VAL Macro
TCP_SYN_QUEUE Structure
TCP_SYN_QUEUE_MAX_ENTRIES Macro
TCP_SYN_QUEUE_TIMEOUT Macro
URG Macro
Variables
NextPort Variable
TFTP
Public Members
TFTPClose Macro
TFTPCloseFile Function
TFTPGet Function
TFTPGetError Macro
TFTPIsFileClosed Function
TFTPIsFileOpened Function
TFTPIsFileOpenReady Macro
TFTPIsGetReady Function
TFTPIsOpened Function
TFTPIsPutReady Function
TFTPOpen Function
TFTPOpenFile Function
TFTPOpenROMFile Function
TFTPPut Function
TFTP_ACCESS_ERROR Enumeration
TFTP_FILE_MODE Enumeration
TFTP_RESULT Enumeration
TFTPGetUploadStatus Function
TFTPUploadFragmentedRAMFileToHost Function
TFTPUploadRAMFileToHost Function
TFTP_CHUNK_DESCRIPTOR Structure
TFTP_UPLOAD_COMPLETE Macro
TFTP_UPLOAD_CONNECT Macro
TFTP_UPLOAD_CONNECT_TIMEOUT Macro
TFTP_UPLOAD_GET_DNS Macro
TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT Macro
TFTP_UPLOAD_RESOLVE_HOST Macro
TFTP_UPLOAD_SEND_DATA Macro
TFTP_UPLOAD_SEND_FILENAME Macro
TFTP_UPLOAD_SERVER_ERROR Macro
TFTP_UPLOAD_WAIT_FOR_CLOSURE Macro
Stack Members
TFTP_ARP_TIMEOUT_VAL Macro
TFTP_GET_TIMEOUT_VAL Macro
TFTP_MAX_RETRIES Macro
Internal Members
MutExVar Variable
TFTP_BLOCK_SIZE Macro
TFTP_BLOCK_SIZE_MSB Macro
TFTP_CLIENT_PORT Macro
TFTP_OPCODE Enumeration
TFTP_SERVER_PORT Macro
TFTP_STATE Enumeration
_tftpError Variable
_tftpFlags Variable
_tftpRetries Variable
_TFTPSendAck Function
_TFTPSendFileName Function
_TFTPSendROMFileName Function
_tftpSocket Variable
_tftpStartTick Variable
_tftpState Variable
smUpload Variable
uploadChunkDescriptor Variable
uploadChunkDescriptorForRetransmit Variable
vUploadFilename Variable
vUploadRemoteHost Variable
wUploadChunkOffset Variable
wUploadChunkOffsetForRetransmit Variable
Tick
Public Members
TICK Type
TICK_HOUR Macro
TICK_MINUTE Macro
TICK_SECOND Macro
TickConvertToMilliseconds Function
TickGet Function
TickGetDiv256 Function
TickGetDiv64K Function
Stack Functions
TickInit Function
TickUpdate Function
Internal Members
dwInternalTicks Variable
GetTickCopy Function
TICKS_PER_SECOND Macro
vTickReading Variable
UDP
Public Members
INVALID_UDP_PORT Macro
INVALID_UDP_SOCKET Macro
UDP_SOCKET Type
UDPOpenEx Function
UDPOpen Macro
UDPClose Function
UDPDiscard Function
UDPFlush Function
UDPGet Function
UDPGetArray Function
UDPIsGetReady Function
UDPIsPutReady Function
UDPPut Function
UDPPutArray Function
UDPPutROMArray Function
UDPPutROMString Function
UDPPutString Function
UDPSetRxBuffer Function
UDPSetTxBuffer Function
UDPIsOpened Function
UDP_OPEN_IP_ADDRESS Macro
UDP_OPEN_NODE_INFO Macro
UDP_OPEN_RAM_HOST Macro
UDP_OPEN_ROM_HOST Macro
UDP_OPEN_SERVER Macro
Stack Members
UDPInit Function
UDPProcess Function
UDPTask Function
Internal Members
activeUDPSocket Variable
FindMatchingSocket Function
LastPutSocket Variable
LOCAL_UDP_PORT_END_NUMBER Macro
LOCAL_UDP_PORT_START_NUMBER Macro
SocketWithRxData Variable
UDP_HEADER Structure
UDP_PORT Type
UDP_SOCKET_INFO Structure
UDPRxCount Variable
UDPSocketInfo Variable
UDPTxCount Variable
wGetOffset Variable
wPutOffset Variable
Types
UDP_STATE Enumeration
Wi-Fi API
Wi-Fi Connection Profile
Connection Profile Public Members
WF_CPCreate Function
WF_CPDelete Function
WF_CPGetAdHocBehavior Function
WF_CPGetBssid Function
WF_CPGetDefaultWepKeyIndex Function
WF_CPGetElements Function
WF_CPGetIds Function
WF_CPGetNetworkType Function
WF_CPGetSecurity Function
WF_CPGetSsid Function
WF_CPSetAdHocBehavior Function
WF_CPSetBssid Function
WF_CPSetDefaultWepKeyIndex Function
WF_CPSetElements Function
WF_CPSetNetworkType Function
WF_CPSetSecurity Function
WF_CPSetSsid Function
WFCPElementsStruct Structure
Connection Profile Internal Members
LowLevel_CPGetElement Function
LowLevel_CPSetElement Function
Wi-Fi Connection Algorithm
Connection Algorithm Public Members
WF_CAGetBeaconTimeout Function
WF_CAGetBeaconTimeoutAction Function
WF_CAGetChannelList Function
WF_CAGetConnectionProfileList Function
WF_CAGetDeauthAction Function
WF_CAGetElements Function
WF_CAGetEventNotificationAction Function
WF_CAGetListenInterval Function
WF_CAGetListRetryCount Function
WF_CAGetMaxChannelTime Function
WF_CAGetMinChannelTime Function
WF_CAGetProbeDelay Function
WF_CAGetRssi Function
WF_CAGetScanCount Function
WF_CAGetScanType Function
WF_CASetBeaconTimeout Function
WF_CASetBeaconTimeoutAction Function
WF_CASetChannelList Function
WF_CASetConnectionProfileList Function
WF_CASetDeauthAction Function
WF_CASetElements Function
WF_CASetEventNotificationAction Function
WF_CASetListenInterval Function
WF_CASetListRetryCount Function
WF_CASetMaxChannelTime Function
WF_CASetMinChannelTime Function
WF_CASetProbeDelay Function
WF_CASetRssi Function
WF_CASetScanCount Function
WF_CASetScanType Function
WFCAElementsStruct Structure
Connection Algorithm Internal Members
LowLevel_CAGetElement Function
LowLevel_CASetElement Function
SetEventNotificationMask Function
Wi-Fi Connection Manager
Connection Manager Public Members
WF_CMConnect Function
WF_CMDisconnect Function
WF_CMGetConnectionState Function
WF_CMInfoGetFSMStats Function
Wi-Fi Scan
Scan Public Members
WF_Scan Function
WF_ScanGetResult Function
Wi-Fi Tx Power Control
Tx Power Control Public Members
WF_TxPowerGetMinMax Function
WF_TxPowerSetMinMax Function
WF_TxPowerGetFactoryMax Function
Wi-Fi Power Save
Power Save Public Members
WF_GetPowerSaveState Function
WF_HibernateEnable Function
WF_PsPollDisable Function
WF_PsPollEnable Function
Power Save Internal Members
SendPowerModeMsg Function
SetPowerSaveState Function
Wi-Fi Miscellaneous
Wi-Fi Miscellaneous Public Members
WF_GetDeviceInfo Function
WF_GetMacAddress Function
WF_GetMacStats Function
WF_GetMultiCastFilter Function
WF_GetRegionalDomain Function
WF_GetRtsThreshold Function
WF_SetMacAddress Function
WF_SetMultiCastFilter Function
WF_SetRegionalDomain Function
WF_SetRtsThreshold Function
tWFDeviceInfoStruct Structure
WFMacStatsStruct Structure
WF_ProcessEvent
Access Point Compatibility
WiFi Tips and Tricks
Hot Topics


Index

Contents | Index | Home
Index
These are all topics and symbols available in this documentation.
_ | A | B | C | D | E | F | G | H | I | L | M | N | O | P | R | S | T | U | V | W | Z
_
_checkIpSrvrResponse variable
_LoadFATRecord function
_MD5_k variable
_MD5_r variable
_NBNS_HEADER structure
_SNMPDuplexInit function
_SNMPGet function
_SNMPGetTxOffset macro
_SNMPPut function
_SNMPSetTxOffset macro
_TFTP_ACCESS_ERROR enumeration
_TFTP_FILE_MODE enumeration
_TFTP_RESULT enumeration
_tftpError variable
_tftpFlags variable
_tftpRetries variable
_TFTPSendAck function
_TFTPSendFileName function
_TFTPSendROMFileName function
_tftpSocket variable
_tftpStartTick variable
_tftpState variable
_updateIpSrvrResponse variable
_Validate function
A
accept function
Access Point Compatibility
Accessing the Demo Application
ACK macro
activeUDPSocket variable
Additional Features
Address
Advanced MPFS2 Settings
AF_INET macro
AGENT_NOTIFY_PORT macro
Announce
Announce Stack Members
AnnounceIP function
APP_CONFIG Structure
appendZeroToOID variable
ARP
Types
ARP Internal Members
ARP Public Members
ARP Stack Members
arp_app_callbacks structure
ARP_IP macro
ARP_OPERATION_REQ macro
ARP_OPERATION_RESP macro
ARP_PACKET structure
ARP_REQ macro
ARP_RESP macro
ARPDeRegisterCallbacks function
ARPInit function
ARPIsResolved function
ARPProcess function
ARPPut function
ARPRegisterCallbacks function
ARPResolve function
ARPSendPkt function
ASN_INT macro
ASN_NULL macro
ASN_OID macro
Authentication
Available Demos
B
Base64Decode function
Base64Encode function
Berkeley (BSD) Sockets
BerkeleySocketInit function
bForceUpdate variable
bind function
Bootloader Design
BSD Sockets
BSD Wrapper Internal Members
BSD Wrapper Public Members
BSD Wrapper Stack Members
BSD_SCK_STATE enumeration
BSDSocket structure
BSDSocketArray variable
btohexa_high function
btohexa_low function
Building MPFS2 Images
C
Cache variable
CalcIPBufferChecksum function
CalcIPChecksum function
CalculateFinishedHash function
Clock Frequency
closesocket function
CloseSocket function
COMMUNITY_TYPE enumeration
Configure your WiFi Access Point
Configuring the Stack
Configuring WiFi Security
connect function
Connecting to the Network
Connection Algorithm Internal Members
Connection Algorithm Public Members
Connection Manager Public Members
Connection Profile Internal Members
Connection Profile Public Members
Cookies
Cooperative Multitasking
CRPeriod variable
curHTTP variable
curHTTPID variable
D
DATA_TYPE enumeration
DATA_TYPE_INFO structure
DATA_TYPE_TABLE_SIZE macro
dataTypeTable variable
Daughter Boards
DDNS_CHECKIP_SERVER macro
DDNS_DEFAULT_PORT macro
DDNS_POINTERS structure
DDNS_SERVICES enumeration
DDNS_STATUS enumeration
DDNSClient variable
DDNSData variable
DDNSForceUpdate function
DDNSGetLastIP function
DDNSGetLastStatus function
DDNSInit function
ddnsServiceHosts variable
ddnsServicePorts variable
DDNSSetService function
DDNSTask function
Demo App
Demo App MDD
Demo Compatibility Table
Demo Information
Demo Modules
Directory Structure
DiscoveryTask function
DNS Client
DNS Internal Members
DNS Public Members
DNS_HEADER structure
DNS_PORT macro
DNS_TIMEOUT macro
DNS_TYPE_A macro
DNS_TYPE_MX macro
DNSBeginUsage function
DNSDiscardName function
DNSEndUsage function
DNSHostName variable
DNSHostNameROM variable
DNSIsResolved function
DNSPutROMString function
DNSPutString function
DNSResolve function
DNSResolveROM function
dwInternalTicks variable
dwLastUpdateTick variable
dwLFSRRandSeed variable
dwSNTPSeconds variable
dwUpdateAt variable
Dynamic DNS Client
Dynamic DNS Internal Members
Dynamic DNS Public Members
Dynamic DNS Stack Members
Dynamic Variables
E
E-mail (SMTP) Demo
ENC28J60 Config
ENCX24J600 Config
Energy Monitoring
Explorer 16 and PIC32 Starter Kit
External Storage
ExtractURLFields function
F
fatCache variable
fatCacheID variable
FIN macro
FindEmailAddress function
FindMatchingSocket function
FindOIDsInRequest function
FindROMEmailAddress function
Flags variable
FormatNetBIOSName function
Forms using GET
Forms using POST
G
gAutoPortNumber variable
GenerateHashRounds function
GenerateRandomDWORD function
GenerateSessionKeys function
Generating Server Certificates
Generic TCP Client
Variables
Generic TCP Server
Macros
GENERIC_TRAP_NOTIFICATION_TYPE enumeration
GenericTCPClient function
GenericTCPServer function
GET_BULK_REQUEST macro
GET_NEXT_REQUEST macro
GET_REQUEST macro
GET_RESPONSE macro
GetDataTypeInfo function
gethostname function
GetNextLeaf function
GetOIDStringByAddr function
GetOIDStringByID function
getSnmpV2GenTrapOid function
GetTickCopy function
Getting Help
Getting Started
getZeroInstance variable
gGenericTrapNotification variable
gOIDCorrespondingSnmpMibID variable
Google PowerMeter
gSendTrapFlag variable
gSendTrapSMstate variable
gSetTrapSendFlag variable
gSnmpNonMibRecInfo variable
gSNMPv3ScopedPduDataPos variable
gSNMPv3ScopedPduRequestBuf variable
gSNMPv3ScopedPduResponseBuf variable
gSnmpv3UserSecurityName variable
gSpecificTrapNotification variable
H
HandlePossibleTCPDisconnection function
HandleTCPSeg function
Hardware Configuration
Hardware Setup
Hash Table Filter Entry Calculator
HASH_SUM structure
HASH_TYPE enumeration
HashAddData function
HashAddROMData function
Hashes
Hashes Internal Members
Hashes Public Members
Hashes Stack Members
hCurrentTCP variable
Helpers
Functions
Variables
Helpers Public Members
hexatob function
hMPFS variable
HOST_TO_PING macro
Hot Topics
How the Stack Works
HSEnd function
HSGet function
HSGetArray function
HSGetWord function
HSPut function
HSPutArray function
HSPutROMArray function
HSPutWord function
HSStart function
HTTP Configuration
HTTP_CACHE_LEN macro
HTTP_CONN structure
HTTP_FILE_TYPE enumeration
HTTP_IO_RESULT enumeration
HTTP_MAX_DATA_LEN macro
HTTP_MAX_HEADER_LEN macro
HTTP_MIN_CALLBACK_FREE macro
HTTP_PORT macro
HTTP_READ_STATUS enumeration
HTTP_STATUS enumeration
HTTP_STUB structure
HTTP_TIMEOUT macro
HTTP2 Authentication
HTTP2 Compression
HTTP2 Cookies
HTTP2 Dynamic Variables
HTTP2 Features
HTTP2 Form Processing
HTTP2 Internal Members
HTTP2 Public Members
HTTP2 Server
HTTP2 Stack Members
HTTPCheckAuth function
httpContentTypes variable
HTTPExecuteGet function
HTTPExecutePost function
httpFileExtensions variable
HTTPGetArg function
HTTPGetROMArg function
HTTPHeaderParseAuthorization function
HTTPHeaderParseContentLength function
HTTPHeaderParseCookie function
HTTPHeaderParseLookup function
HTTPIncFile function
HTTPInit function
HTTPLoadConn function
HTTPMPFSUpload function
HTTPNeedsAuth function
HTTPPostConfig function
HTTPPostDDNSConfig function
HTTPPostEmail function
HTTPPostLCD function
HTTPPostMD5 function
HTTPPostSNMPCommunity function
HTTPPrint_varname function
HTTPProcess function
HTTPReadPostName function
HTTPReadPostPair macro
HTTPReadPostValue function
HTTPReadTo function
HTTPRequestHeaders variable
HTTPResponseHeaders variable
HTTPS_PORT macro
HTTPSendFile function
HTTPServer function
httpStubs variable
HTTPURLDecode function
HW_ETHERNET macro
I
ICMP
ICMP Internal Members
ICMP Public Members
ICMP_PACKET structure
ICMP_TIMEOUT macro
ICMPBeginUsage function
ICMPEndUsage function
ICMPFlags variable
ICMPGetReply function
ICMPProcess function
ICMPSendPing function
ICMPSendPingToHost function
ICMPSendPingToHostROM function
ICMPSendPingToHostROM macro
ICMPState variable
ICMPTimer variable
ifconfig Commands
in_addr structure
INADDR_ANY macro
INDEX_INFO union
Initialization
Initialization Structure
INOUT_SNMP_PDU enumeration
Internet Bootloader
Internet Radio
Introduction
INVALID_SOCKET macro
INVALID_TCP_PORT macro
INVALID_UDP_PORT macro
INVALID_UDP_SOCKET macro
IP Address
IP_ADDR_ANY macro
iperf Example
IPPROTO_IP macro
IPPROTO_TCP macro
IPPROTO_UDP macro
IS_AGENT_PDU macro
IS_ASN_INT macro
IS_ASN_NULL macro
IS_GET_NEXT_REQUEST macro
IS_GET_REQUEST macro
IS_GET_RESPONSE macro
IS_OCTET_STRING macro
IS_OID macro
IS_SET_REQUEST macro
IS_SNMPV3_AUTH_STRUCTURE macro
IS_STRUCTURE macro
IS_TRAP macro
IsASNNull function
isBufferUsed variable
isHashUsed variable
isMPFSLocked variable
isStubUsed variable
IsValidCommunity function
IsValidInt function
IsValidLength function
IsValidOID function
IsValidPDU function
IsValidStructure function
iwconfig Commands
iwpriv Commands
L
lastBlock variable
lastFailure variable
lastKnownIP variable
LastPutSocket variable
lastRead variable
lastStatus variable
lastSuccess variable
leftRotateDWORD function
leftRotateDWORD macro
LFSRRand function
LFSRSeedRand function
listen function
LoadOffChip function
LOCAL_PORT_END_NUMBER macro
LOCAL_PORT_START_NUMBER macro
LOCAL_UDP_PORT_END_NUMBER macro
LOCAL_UDP_PORT_START_NUMBER macro
LowLevel_CAGetElement function
LowLevel_CASetElement function
LowLevel_CPGetElement function
LowLevel_CPSetElement function
M
MAC Address
Main File
Main Loop
masks variable
MAX_FILE_NAME_LEN macro
MAX_REG_APPS macro
MAX_TELNET_CONNECTIONS macro
MAX_TRY_TO_SEND_TRAP macro
MD5AddData function
MD5AddROMData function
MD5Calculate function
MD5HashBlock function
MD5Initialize function
Memory Allocation
Memory Usage
MIB Browsers
MIB Files
MIB_INFO union
Microchip TCP/IP Discoverer
MPFS_FAT_RECORD structure
MPFS_HANDLE type
MPFS_INVALID macro
MPFS_INVALID_FAT macro
MPFS_INVALID_HANDLE macro
MPFS_PTR type
MPFS_SEEK_MODE enumeration
MPFS_STUB structure
MPFS_WRITE_PAGE_SIZE macro
MPFS2
MPFS2 Command Line Options
MPFS2 Internal Members
MPFS2 Public Members
MPFS2 Stack Members
MPFS2 Utility
MPFS2_FLAG_HASINDEX macro
MPFS2_FLAG_ISZIPPED macro
MPFSClose function
MPFSFormat function
MPFSGet function
MPFSGetArray function
MPFSGetBytesRem function
MPFSGetEndAddr function
MPFSGetFilename function
MPFSGetFlags function
MPFSGetID function
MPFSGetLong function
MPFSGetMicrotime function
MPFSGetPosition function
MPFSGetSize function
MPFSGetStartAddr function
MPFSGetTimestamp function
MPFSInit function
MPFSOpen function
MPFSOpenID function
MPFSOpenROM function
MPFSPutArray function
MPFSPutEnd function
MPFSSeek function
MPFSStubs variable
MPFSTell macro
msgSecrtyParamLenOffset variable
MutExVar variable
MySocket variable
MyTCB variable
MyTCBStub variable
N
NBNS
NBNS Stack Members
NBNS_HEADER structure
NBNS_PORT macro
NBNSGetName function
NBNSPutName function
NBNSTask function
Network Management (SNMP) Server
Functions
Macros
Variables
NextPort variable
NOTIFY_COMMUNITY_LEN macro
NTP_EPOCH macro
NTP_FAST_QUERY_INTERVAL macro
NTP_PACKET structure
NTP_QUERY_INTERVAL macro
NTP_REPLY_TIMEOUT macro
NTP_SERVER macro
NTP_SERVER_PORT macro
numFiles variable
O
OCTET_STRING macro
OID_INFO structure
OID_MAX_LEN macro
OIDLookup function
P
PDU_INFO structure
Performance Test Internal Members
Performance Test Stack Members
Performance Tests
PERFORMANCE_PORT macro
Peripheral Usage
PIC18 Explorer
PIC18F97J60 Config
PIC24FJ256DA210 Dev Board
PIC32MX7XX Config
PICDEM.net 2
Ping (ICMP) Demo
Macros
PingDemo function
Power Save Internal Members
Power Save Public Members
ProcessGetBulkVar function
ProcessGetNextVar function
ProcessGetSetHeader function
ProcessGetVar function
ProcessHeader function
ProcessSetVar function
ProcessSnmpv3MsgData function
ProcessVariables function
Programming and First Run
Protocol Configuration
Protocol Macros and Files
PSH macro
ptrHS variable
PutHeadersState variable
R
ReadMIBRecord function
ReadProgramMemory function
Reboot
Reboot Stack Members
REBOOT_PORT macro
REBOOT_SAME_SUBNET_ONLY macro
RebootTask function
RecordType variable
recv function
recvfrom function
reg_apps variable
Release Notes
RemoteURL variable
Replace function
REPORT_RESPONSE macro
Required Files
reqVarErrStatus structure
RESERVED_HTTP_MEMORY macro
RESERVED_SSL_MEMORY macro
ResolvedInfo variable
ResponseCode variable
ROMStringToIPAddress function
ROMStringToIPAddress macro
RST macro
RTOS
RX_PERFORMANCE_PORT macro
RXParserState variable
S
SaveOffChip function
Scan Public Members
send function
SendNotification function
SendPowerModeMsg function
SendTCP function
SENDTCP_KEEP_ALIVE macro
SENDTCP_RESET_TIMERS macro
sendto function
SERVER_PORT macro
ServerName variable
ServerPort variable
SET_REQUEST macro
SetErrorStatus function
SetEventNotificationMask function
SetPowerSaveState function
SHA1AddData function
SHA1AddROMData function
SHA1Calculate function
SHA1HashBlock function
SHA1Initialize function
Silicon Solutions
sktHTTP macro
SM_HTTP2 enumeration
SM_SSL_RX_SERVER_HELLO enumeration
smDNS variable
smHTTP macro
SMTP Client
SMTP Client Examples
SMTP Client Internal Members
SMTP Client Long Message Example
SMTP Client Public Members
SMTP Client Short Message Example
SMTP Client Stack Members
SMTP_CONNECT_ERROR macro
SMTP_POINTERS structure
SMTP_PORT macro
SMTP_RESOLVE_ERROR macro
SMTP_SERVER_REPLY_TIMEOUT macro
SMTP_SUCCESS macro
SMTPBeginUsage function
SMTPClient variable
SMTPDemo function
SMTPEndUsage function
SMTPFlags variable
SMTPFlush function
SMTPIsBusy function
SMTPIsPutReady function
SMTPPut function
SMTPPutArray function
SMTPPutDone function
SMTPPutROMArray function
SMTPPutROMString function
SMTPPutString function
SMTPSendMail function
SMTPServer variable
SMTPState variable
SMTPTask function
smUpload variable
SNMP
Functions
Macros
Types
Variables
SNMP Internal Members
SNMP Operations
SNMP Public Members
SNMP Stack Members
SNMP Traps
SNMP_ACTION enumeration
SNMP_AGENT_PORT macro
SNMP_BIB_FILE_NAME macro
SNMP_COMMUNITY_MAX_LEN macro
SNMP_COUNTER32 macro
SNMP_END_OF_VAR macro
SNMP_ERR_STATUS enumeration
SNMP_GAUGE32 macro
SNMP_ID type
SNMP_INDEX type
SNMP_INDEX_INVALID macro
SNMP_IP_ADDR macro
SNMP_MAX_MSG_SIZE macro
SNMP_MAX_NON_REC_ID_OID macro
SNMP_NMS_PORT macro
SNMP_NOTIFY_INFO structure
SNMP_NSAP_ADDR macro
SNMP_OPAQUE macro
SNMP_START_OF_VAR macro
SNMP_STATUS union
SNMP_TIME_TICKS macro
SNMP_V1 macro
SNMP_V2C macro
SNMP_V3 macro
SNMP_VAL union
SNMPAgentSocket variable
SNMPCheckIfPvtMibObjRequested function
SNMPGetExactIndex function
SNMPGetNextIndex function
SNMPGetTimeStamp function
SNMPGetVar function
SNMPIdRecrdValidation function
SNMPInit function
SNMPIsNotifyReady function
SNMPIsValidSetLen function
SNMPNONMIBRECDINFO structure
SNMPNotify function
SNMPNotifyInfo variable
SNMPNotifyPrepare function
snmpReqVarErrStatus variable
SNMPRxOffset variable
SNMPSendTrap function
SNMPSetVar function
SNMPStatus variable
SNMPTask function
SNMPTxOffset variable
Snmpv3AESDecryptRxedScopedPdu function
Snmpv3BufferPut function
Snmpv3FormulateEngineID function
Snmpv3GetAuthEngineTime function
Snmpv3GetBufferData function
Snmpv3InitializeUserDataBase function
SNMPV3MSGDATA structure
Snmpv3MsgProcessingModelProcessPDU function
Snmpv3Notify function
Snmpv3ScopedPduProcessing function
Snmpv3TrapScopedpdu function
Snmpv3UserSecurityModelProcessPDU function
Snmpv3UsmAesEncryptDecryptInitVector function
Snmpv3UsmOutMsgAuthenticationParam function
Snmpv3ValidateEngineId function
Snmpv3ValidateSecNameAndSecLvl function
Snmpv3ValidateSecurityName function
SNMPValidateCommunity function
SNTP Client
SNTP Client Internal Members
SNTP Client Public Members
SNTP Client Stack Members
SNTPClient function
SNTPGetUTCSeconds function
SOCK_DGRAM macro
SOCK_STREAM macro
sockaddr structure
SOCKADDR type
sockaddr_in structure
SOCKADDR_IN type
socket function
SOCKET type
Socket Types
SOCKET_CNXN_IN_PROGRESS macro
SOCKET_DISCONNECTED macro
SOCKET_ERROR macro
SOCKET_INFO structure
Sockets
SocketWithRxData variable
Software
SSL
SSL Internal Members
SSL Public Members
SSL Stack Members
SSL_ALERT macro
SSL_ALERT_LEVEL enumeration
SSL_APPLICATION macro
SSL_BASE_BUFFER_ADDR macro
SSL_BASE_HASH_ADDR macro
SSL_BASE_KEYS_ADDR macro
SSL_BASE_SESSION_ADDR macro
SSL_BASE_STUB_ADDR macro
SSL_BUFFER union
SSL_BUFFER_SIZE macro
SSL_BUFFER_SPACE macro
SSL_CERT variable
SSL_CERT_LEN variable
SSL_CHANGE_CIPHER_SPEC macro
SSL_HANDSHAKE macro
SSL_HASH_SIZE macro
SSL_HASH_SPACE macro
SSL_INVALID_ID macro
SSL_KEYS structure
SSL_KEYS_SIZE macro
SSL_KEYS_SPACE macro
SSL_MESSAGES enumeration
SSL_MIN_SESSION_LIFETIME macro
SSL_PKEY_INFO structure
SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 macro
SSL_RSA_LIFETIME_EXTENSION macro
SSL_RSA_WITH_ARCFOUR_128_MD5 macro
SSL_SESSION structure
SSL_SESSION_SIZE macro
SSL_SESSION_SPACE macro
SSL_SESSION_STUB structure
SSL_SESSION_TYPE enumeration
SSL_STATE enumeration
SSL_STUB structure
SSL_STUB_SIZE macro
SSL_STUB_SPACE macro
SSL_SUPPLEMENTARY_DATA_TYPES enumeration
SSL_VERSION macro
SSL_VERSION_HI macro
SSL_VERSION_LO macro
SSLBufferAlloc function
SSLBufferFree function
sslBufferID variable
SSLBufferSync function
SSLFinishPartialRecord macro
SSLFlushPartialRecord macro
sslHash variable
SSLHashAlloc function
SSLHashFree function
sslHashID variable
SSLHashSync function
SSLInit function
sslKeys variable
sslKeysID variable
SSLKeysSync function
SSLMACAdd function
SSLMACBegin function
SSLMACCalc function
SSLPeriodic function
SSLRSAOperation function
sslRSAStubID variable
SSLRxAlert function
SSLRxAntiqueClientHello function
SSLRxCCS function
SSLRxClientHello function
SSLRxClientKeyExchange function
SSLRxFinished function
SSLRxHandshake function
SSLRxRecord function
SSLRxServerCertificate function
SSLRxServerHello function
sslSession variable
sslSessionID variable
SSLSessionMatchID function
SSLSessionMatchIP function
SSLSessionNew function
sslSessionStubs variable
SSLSessionSync function
SSLSessionUpdated macro
sslSessionUpdated variable
SSLStartPartialRecord function
SSLStartSession function
sslStub variable
SSLStubAlloc function
SSLStubFree function
sslStubID variable
SSLStubSync function
SSLTerminate function
SSLTxCCSFin function
SSLTxClientHello function
SSLTxClientKeyExchange function
SSLTxMessage function
SSLTxRecord function
SSLTxServerCertificate function
SSLTxServerHello function
SSLTxServerHelloDone function
Stack API
Stack Architecture
Stack Performance
STACK_USE_SMIV2 macro
Standalone Commands
StaticVars variable
strAuthenticated variable
strDisplay variable
strGoodBye variable
stricmppgm2ram function
StringToIPAddress function
strnchr function
strPassword variable
strSpaces variable
strTitle variable
STRUCTURE macro
strupr function
SW License Agreement
SwapARPPacket function
swapl function
swaps function
SwapTCPHeader function
SYN macro
SyncTCB function
SyncTCBStub macro
SYNQueue variable
T
TCB structure
TCB_STUB structure
TCBStubs variable
TCP
Variables
TCP Internal Members
TCP Public Members
TCP Stack Members
TCP/IP Configuration Wizard
TCP_ADJUST_GIVE_REST_TO_RX macro
TCP_ADJUST_GIVE_REST_TO_TX macro
TCP_ADJUST_PRESERVE_RX macro
TCP_ADJUST_PRESERVE_TX macro
TCP_AUTO_TRANSMIT_TIMEOUT_VAL macro
TCP_CLOSE_WAIT_TIMEOUT macro
TCP_DELAYED_ACK_TIMEOUT macro
TCP_FIN_WAIT_2_TIMEOUT macro
TCP_HEADER structure
TCP_KEEP_ALIVE_TIMEOUT macro
TCP_MAX_RETRIES macro
TCP_MAX_SEG_SIZE_RX macro
TCP_MAX_SEG_SIZE_TX macro
TCP_MAX_SYN_RETRIES macro
TCP_MAX_UNACKED_KEEP_ALIVES macro
TCP_OPEN_IP_ADDRESS macro
TCP_OPEN_NODE_INFO macro
TCP_OPEN_RAM_HOST macro
TCP_OPEN_ROM_HOST macro
TCP_OPEN_SERVER macro
TCP_OPTIMIZE_FOR_SIZE macro
TCP_OPTIONS structure
TCP_OPTIONS_END_OF_LIST macro
TCP_OPTIONS_MAX_SEG_SIZE macro
TCP_OPTIONS_NO_OP macro
TCP_SOCKET type
TCP_SOCKET_COUNT macro
TCP_START_TIMEOUT_VAL macro
TCP_STATE enumeration
TCP_SYN_QUEUE structure
TCP_SYN_QUEUE_MAX_ENTRIES macro
TCP_SYN_QUEUE_TIMEOUT macro
TCP_WINDOW_UPDATE_TIMEOUT_VAL macro
TCPAddSSLListener function
TCPAdjustFIFOSize function
TCPClose function
TCPConnect macro
TCPDiscard function
TCPDisconnect function
TCPFind macro
TCPFindArray macro
TCPFindArrayEx function
TCPFindEx function
TCPFindROMArray macro
TCPFindROMArrayEx function
TCPFlush function
TCPGet function
TCPGetArray function
TCPGetRemoteInfo function
TCPGetRxFIFOFree function
TCPGetRxFIFOFull macro
TCPGetTxFIFOFree macro
TCPGetTxFIFOFull function
TCPInit function
TCPIP Demo App Features by Hardware Platform
TCPIsConnected function
TCPIsGetReady function
TCPIsPutReady function
TCPIsSSL function
TCPListen macro
TCPOpen function
TCPPeek function
TCPPeekArray function
TCPPerformanceTask function
TCPProcess function
TCPPut function
TCPPutArray function
TCPPutROMArray function
TCPPutROMString function
TCPPutString function
TCPRAMCopy function
TCPRAMCopyROM function
TCPRequestSSLMessage function
TCPRXPerformanceTask function
TCPSSLDecryptMAC function
TCPSSLGetPendingTxSize function
TCPSSLHandleIncoming function
TCPSSLHandshakeComplete function
TCPSSLInPlaceMACEncrypt function
TCPSSLIsHandshaking function
TCPSSLPutRecordHeader function
TCPStartSSLClient function
TCPStartSSLClientEx function
TCPStartSSLServer function
TCPTick function
TCPTXPerformanceTask function
TCPWasReset function
Telnet
Telnet Internal Members
Telnet Public Members
Telnet Stack Members
TELNET_PASSWORD macro
TELNET_PORT macro
TELNET_USERNAME macro
TELNETS_PORT macro
TelnetTask function
TFTP
TFTP Internal Members
TFTP Public Members
TFTP Stack Members
TFTP_ACCESS_ERROR enumeration
TFTP_ARP_TIMEOUT_VAL macro
TFTP_BLOCK_SIZE macro
TFTP_BLOCK_SIZE_MSB macro
TFTP_CHUNK_DESCRIPTOR structure
TFTP_CLIENT_PORT macro
TFTP_END_OF_FILE enumeration member
TFTP_ERROR enumeration member
TFTP_ERROR_ACCESS_VIOLATION enumeration member
TFTP_ERROR_DISK_FULL enumeration member
TFTP_ERROR_FILE_EXISTS enumeration member
TFTP_ERROR_FILE_NOT_FOUND enumeration member
TFTP_ERROR_INVALID_OPERATION enumeration member
TFTP_ERROR_NO_SUCH_USE enumeration member
TFTP_ERROR_NOT_DEFINED enumeration member
TFTP_ERROR_UNKNOWN_TID enumeration member
TFTP_FILE_MODE enumeration
TFTP_FILE_MODE_READ enumeration member
TFTP_FILE_MODE_WRITE enumeration member
TFTP_GET_TIMEOUT_VAL macro
TFTP_MAX_RETRIES macro
TFTP_NOT_READY enumeration member
TFTP_OK enumeration member
TFTP_OPCODE enumeration
TFTP_RESULT enumeration
TFTP_RETRY enumeration member
TFTP_SERVER_PORT macro
TFTP_STATE enumeration
TFTP_TIMEOUT enumeration member
TFTP_UPLOAD_COMPLETE macro
TFTP_UPLOAD_CONNECT macro
TFTP_UPLOAD_CONNECT_TIMEOUT macro
TFTP_UPLOAD_GET_DNS macro
TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT macro
TFTP_UPLOAD_RESOLVE_HOST macro
TFTP_UPLOAD_SEND_DATA macro
TFTP_UPLOAD_SEND_FILENAME macro
TFTP_UPLOAD_SERVER_ERROR macro
TFTP_UPLOAD_WAIT_FOR_CLOSURE macro
TFTPClose macro
TFTPCloseFile function
TFTPGet function
TFTPGetError macro
TFTPGetUploadStatus function
TFTPIsFileClosed function
TFTPIsFileOpened function
TFTPIsFileOpenReady macro
TFTPIsGetReady function
TFTPIsOpened function
TFTPIsPutReady function
TFTPOpen function
TFTPOpenFile function
TFTPOpenROMFile function
TFTPPut function
TFTPUploadFragmentedRAMFileToHost function
TFTPUploadRAMFileToHost function
Tick Internal Members
Tick Module
Tick Public Members
Tick Stack Functions
TICK type
TICK_HOUR macro
TICK_MINUTE macro
TICK_SECOND macro
TickConvertToMilliseconds function
TickGet function
TickGetDiv256 function
TickGetDiv64K function
TickInit function
TICKS_PER_SECOND macro
TickUpdate function
TransportState variable
TRAP macro
TRAP_COMMUNITY_MAX_LEN macro
TRAP_INFO structure
TRAP_TABLE_SIZE macro
trapInfo variable
tWFDeviceInfoStruct structure
Tx Power Control Public Members
TX_PERFORMANCE_PORT macro
U
UART-to-TCP Bridge
UDP
Types
UDP Internal Members
UDP Public Members
UDP Sockets
UDP Stack Members
UDP_HEADER structure
UDP_OPEN_IP_ADDRESS macro
UDP_OPEN_NODE_INFO macro
UDP_OPEN_RAM_HOST macro
UDP_OPEN_ROM_HOST macro
UDP_OPEN_SERVER macro
UDP_PORT type
UDP_SOCKET type
UDP_SOCKET_INFO structure
UDP_STATE enumeration
UDPClose function
UDPDiscard function
UDPFlush function
UDPGet function
UDPGetArray function
UDPInit function
UDPIsGetReady function
UDPIsOpened function
UDPIsPutReady function
UDPOpen macro
UDPOpenEx function
UDPPerformanceTask function
UDPProcess function
UDPPut function
UDPPutArray function
UDPPutROMArray function
UDPPutROMString function
UDPPutString function
UDPRxCount variable
UDPSetRxBuffer function
UDPSetTxBuffer function
UDPSocketInfo variable
UDPTask function
UDPTxCount variable
uitoa function
ultoa function
UnencodeURL function
UNKNOWN_SOCKET macro
uploadChunkDescriptor variable
uploadChunkDescriptorForRetransmit variable
Uploading Pre-built MPFS2 Images
Uploading Web Pages
URG macro
Using the Bootloader
Using the Stack
V
VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE enumeration
vTickReading variable
vUploadFilename variable
vUploadRemoteHost variable
W
Web Page Demos
Functions
Variables
WebVend
WF_CAGetBeaconTimeout function
WF_CAGetBeaconTimeoutAction function
WF_CAGetChannelList function
WF_CAGetConnectionProfileList function
WF_CAGetDeauthAction function
WF_CAGetElements function
WF_CAGetEventNotificationAction function
WF_CAGetListenInterval function
WF_CAGetListRetryCount function
WF_CAGetMaxChannelTime function
WF_CAGetMinChannelTime function
WF_CAGetProbeDelay function
WF_CAGetRssi function
WF_CAGetScanCount function
WF_CAGetScanType function
WF_CASetBeaconTimeout function
WF_CASetBeaconTimeoutAction function
WF_CASetChannelList function
WF_CASetConnectionProfileList function
WF_CASetDeauthAction function
WF_CASetElements function
WF_CASetEventNotificationAction function
WF_CASetListenInterval function
WF_CASetListRetryCount function
WF_CASetMaxChannelTime function
WF_CASetMinChannelTime function
WF_CASetProbeDelay function
WF_CASetRssi function
WF_CASetScanCount function
WF_CASetScanType function
WF_CMConnect function
WF_CMDisconnect function
WF_CMGetConnectionState function
WF_CMInfoGetFSMStats function
WF_CPCreate function
WF_CPDelete function
WF_CPGetAdHocBehavior function
WF_CPGetBssid function
WF_CPGetDefaultWepKeyIndex function
WF_CPGetElements function
WF_CPGetIds function
WF_CPGetNetworkType function
WF_CPGetSecurity function
WF_CPGetSsid function
WF_CPSetAdHocBehavior function
WF_CPSetBssid function
WF_CPSetDefaultWepKeyIndex function
WF_CPSetElements function
WF_CPSetNetworkType function
WF_CPSetSecurity function
WF_CPSetSsid function
WF_GetDeviceInfo function
WF_GetMacAddress function
WF_GetMacStats function
WF_GetMultiCastFilter function
WF_GetPowerSaveState function
WF_GetRegionalDomain function
WF_GetRtsThreshold function
WF_HibernateEnable function
WF_ProcessEvent
WF_PsPollDisable function
WF_PsPollEnable function
WF_Scan function
WF_ScanGetResult function
WF_SetMacAddress function
WF_SetMultiCastFilter function
WF_SetRegionalDomain function
WF_SetRtsThreshold function
WF_TxPowerGetFactoryMax function
WF_TxPowerGetMinMax function
WF_TxPowerSetMinMax function
WFCAElementsStruct structure
WFCPElementsStruct structure
WFMacStatsStruct structure
wGetOffset variable
wICMPSequenceNumber variable
Wi-Fi API
Wi-Fi Connection Algorithm
Wi-Fi Connection Manager
Wi-Fi Connection Profile
WiFi Console
WiFi EZConfig
Wi-Fi Miscellaneous
Wi-Fi Miscellaneous Public Members
Wi-Fi Power Save
Wi-Fi Scan
WiFi Tips and Tricks
Wi-Fi Tx Power Control
wPutOffset variable
wUploadChunkOffset variable
wUploadChunkOffsetForRetransmit variable
Z
Zero Configuration (ZeroConf)


Introduction

Contents | Index
Next
Introduction
Welcome to the Microchip TCP/IP Stack!

The Microchip 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.

Updates

The latest version of the Microchip TCP/IP Stack is always available at [image] http://www.microchip.com/tcpip. New features are constantly being added, so check there periodically for updates and bug fixes.

Wi-Fi® is a registered trademark of the Wi-Fi Alliance.

Topics
Name | Description
Getting Help | Where to get help for the TCP/IP Stack
Directory Structure | Describes where to find files in the TCP/IP Stack.
Introduction


MAX_TELNET_CONNECTIONS Macro

Contents | Index | Home
Previous | Up | Next
MAX_TELNET_CONNECTIONS Macro
C
#define MAX_TELNET_CONNECTIONS (1u)
Description

Number of simultaneously allowed Telnet sessions. Note that you must have an equal number of TCP_PURPOSE_TELNET type TCP sockets declared in the TCPSocketInitializer[] array above for multiple connections to work. If fewer sockets are available than this definition, then the the lesser of the two quantities will be the actual limit.

Stack API > Telnet > Public Members > MAX_TELNET_CONNECTIONS Macro


strAuthenticated Variable

Contents | Index | Home
Previous | Up | Next
strAuthenticated Variable
C
ROM BYTE strAuthenticated[] = "\r\nLogged in successfully\r\n\r\n" "\r\nPress 'q' to quit\r\n";
Description

Successful authentication message

Stack API > Telnet > Internal Members > strAuthenticated Variable


strDisplay Variable

Contents | Index | Home
Previous | Up | Next
strDisplay Variable
C
ROM BYTE strDisplay[] = "\r\nSNTP Time:    (disabled)" "\r\nAnalog:             1023" "\r\nButtons:         3 2 1 0" "\r\nLEDs:    7 6 5 4 3 2 1 0";
Description

Demo output string

Stack API > Telnet > Internal Members > strDisplay Variable


strGoodBye Variable

Contents | Index | Home
Previous | Up | Next
strGoodBye Variable
C
ROM BYTE strGoodBye[] = "\r\n\r\nGoodbye!\r\n";
Description

Demo disconnection message

Stack API > Telnet > Internal Members > strGoodBye Variable


strPassword Variable

Contents | Index | Home
Previous | Up | Next
strPassword Variable
C
ROM BYTE strPassword[] = "Password: \xff\xfd\x2d";
Description

DO Suppress Local Echo (stop telnet client from printing typed characters) Access denied message

Stack API > Telnet > Internal Members > strPassword Variable


strSpaces Variable

Contents | Index | Home
Previous | Up | Next
strSpaces Variable
C
ROM BYTE strSpaces[] = "          ";
Description

String with extra spaces, for Demo

Stack API > Telnet > Internal Members > strSpaces Variable


strTitle Variable

Contents | Index | Home
Previous | Up | Next
strTitle Variable
C
ROM BYTE strTitle[] = "\x1b[2J\x1b[31m\x1b[1m" "Microchip Telnet Server 1.1\x1b[0m\r\n" "(for this demo, type 'admin' for the login and 'microchip' for the password.)\r\n" "Login: ";
Description

Demo title string

Stack API > Telnet > Internal Members > strTitle Variable


Telnet

Contents | Index | Home
Previous | Up | Next
Telnet

Telnet provides bidirectional, interactive communication between two nodes on the Internet or on a Local Area Network. The Telnet 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 function to include the functionality you'd like. You may insert or change states in TelnetTask as needed.

Topics
Name | Description
Telnet Public Members | Functions and variables accessible by the stack application
Telnet Stack Members | Functions and variables intended to be accessed only by the stack
Telnet Internal Members | Functions and variables internal to the Telnet module
Stack API > Telnet


Telnet Internal Members

Contents | Index | Home
Previous | Up | Next
Telnet Internal Members

The following functions and variables are designated as internal to the Telnet module.

Module

Telnet

Variables
Name | Description
strSpaces | String with extra spaces, for Demo
strAuthenticated | Successful authentication message
strDisplay | Demo output string
strGoodBye | Demo disconnection message
strPassword | DO Suppress Local Echo (stop telnet client from printing typed characters) Access denied message
strTitle | Demo title string
Stack API > Telnet > Internal Members


Telnet Public Members

Contents | Index | Home
Previous | Up | Next
Telnet Public Members

The following functions and variables are available to the stack application.

Macros
Name | Description
MAX_TELNET_CONNECTIONS | Number of simultaneously allowed Telnet sessions. Note that you must have an equal number of TCP_PURPOSE_TELNET type TCP sockets declared in the TCPSocketInitializer[] array above for multiple connections to work. If fewer sockets are available than this definition, then the the lesser of the two quantities will be the actual limit.
TELNET_PASSWORD | Default Telnet password
TELNET_PORT | Default local listening port for the Telnet server. Port 23 is the protocol default.
TELNETS_PORT | Default local listening port for the Telnet server when SSL secured. Port 992 is the telnets protocol default.
TELNET_USERNAME | Default username and password required to login to the Telnet server.
Module

Telnet

Stack API > Telnet > Public Members


Telnet Stack Members

Contents | Index | Home
Previous | Up | Next
Telnet Stack Members

The following functions and variables are public, but are intended only to be accessed by the stack itself. Applications should generally not call these functions or modify these variables.

Functions
Name | Description
TelnetTask | Performs Telnet Server related tasks. Contains the Telnet state machine and state tracking variables.
Module

Telnet

Stack API > Telnet > Stack Members


TELNET_PASSWORD Macro

Contents | Index | Home
Previous | Up | Next
TELNET_PASSWORD Macro
C
#define TELNET_PASSWORD "microchip"
Description

Default Telnet password

Stack API > Telnet > Public Members > TELNET_PASSWORD Macro


TELNET_PORT Macro

Contents | Index | Home
Previous | Up | Next
TELNET_PORT Macro
C
#define TELNET_PORT 23
Description

Default local listening port for the Telnet server. Port 23 is the protocol default.

Stack API > Telnet > Public Members > TELNET_PORT Macro


TELNET_USERNAME Macro

Contents | Index | Home
Previous | Up | Next
TELNET_USERNAME Macro
C
#define TELNET_USERNAME "admin"
Description

Default username and password required to login to the Telnet server.

Stack API > Telnet > Public Members > TELNET_USERNAME Macro


TELNETS_PORT Macro

Contents | Index | Home
Previous | Up | Next
TELNETS_PORT Macro
C
#define TELNETS_PORT 992
Description

Default local listening port for the Telnet server when SSL secured. Port 992 is the telnets protocol default.

Stack API > Telnet > Public Members > TELNETS_PORT Macro


TelnetTask Function

Contents | Index | Home
Previous | Up | Next
TelnetTask Function
C
void TelnetTask();
Description

Performs Telnet Server related tasks. Contains the Telnet state machine and state tracking variables.

Preconditions

Stack is initialized()

Returns

None

Side Effects

None

Remarks

None

Stack API > Telnet > Stack Members > TelnetTask Function