Microchip TCP/IP Stack Help

E-mail (SMTP) Demo ( see page 100)

Description

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.

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 ( see page 92) topic.

Generic TCP Client ( see page 101)

Demonstrates how to build a TCP Client application through an HTTP client example.

Demonstrates how to build a TCP server application

Generic TCP Server ( see page 104)

Ping (ICMP) Demo ( see page 105)

Demonstrates how to build a Ping client.

HTTPPostConfig ( see page 95)

Describes the Simple Network Management Protocol Demo.

Description

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

For Microchip 802.11b/g WiFi PICtail MRF24W, the following network types are supported.

• CFG_WF_INFRASTRUCTURE

• CFG_WF_ADHOC

• CFG_WF_P2P (supported by MRF24WG0M only)

For Microchip 802.11b/g WiFi PICtail MRF24W, the new security modes are supported.

• WF_SECURITY_WPS_PUSH_BUTTON (supported by MRF24WG0M only)

• WF_SECURITY_WPS_PIN (supported by MRF24WG0M only)

7.2.1.2.1

Web Page Demos

Functions

Name Description

HTTPPostImage ( see page

95)

This is function HTTPPostImage.

Processes the configuration form on config/index.htm

HTTPPostSNMPCommunity

( see page 96)

This is function HTTPPostSNMPCommunity.

Parsing and collecting http data received from http form.

HTTPPostDDNSConfig ( see page 96)

HTTPPostEmail ( see page

96)

HTTPPostLCD ( see page

HTTPPostMD5 ( see page

ImageUpdate_Addr ( see page 98)

Processes the e-mail form on email/index.htm

Processes the LCD form on forms.htm

Processes the file upload form on upload.htm

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

Variables

Name

Flag_ImageUpdate_running

( see page 98)

Description

This is variable Flag_ImageUpdate_running.

Processes the file upload form on upload_Image.htm

DDNSData ( see page 99)

RAM allocated for DDNS parameters

This is variable ImageUpdate_Checksum.

ImageUpdate_Checksum ( see page 99)

ImageUpdate_Size ( see page 99)

This is variable ImageUpdate_Size.

lastFailure ( see page 99)

Stick status message variable. See lastSuccess ( see page 100) for details.

lastSuccess ( see page 100) 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.

Description

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 ( see page 91), processing web forms (using HTTP GET and POST), and providing status information through the output of

dynamic variables.

7.2.1.2.1.1

Dynamic Variables

Module

implement dynamic variables in your own page, see the HTTP2 dynamic variables topic ( see page 236).

Description

Overview

This section describes how to view dynamic variables in the TCP/IP Demo App HTTP2 demo. For information about how to

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

( see page 88) 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

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

You can optionally complete the exercises described on the Dynamic Variables page. You may want to read the HTTP2 dynamic variables topic ( see page 236) 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.

7.2.1.2.1.2

Authentication

Module

how to implement authentication in your own page, see the HTTP2 Authentication topic ( see page 241).

Description

Overview

This section describes how to use the authentication demo in the TCP/IP Demo App HTTP2 demo. For information about

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 ( see page 247) function.

3. Change the values being compared to the function inputs to a username and password of you choosing.

7.2 Available Demos Microchip TCP/IP Stack Help

4. Rebuild your project and program your board.

Demo App

7.2.1.2.1.3

Forms using GET

Module

implement forms in your own page, see the HTTP2 form processing topic ( see page 238).

Description

Overview

This section describes how to use web forms in the TCP/IP Demo App HTTP2 demo. For information about how to

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 ( see page 88) 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 ( see page 238) 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 ( see page 247)

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.

7.2.1.2.1.4

Forms using POST

Module

implement forms in your own page, see the HTTP2 form processing topic ( see page 238).

Description

Overview

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

This section describes how to use web forms in the TCP/IP Demo App HTTP2 demo. For information about how to

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. [email protected] 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 ( see page 176)

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 ( see page 467) topic for

more information.

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

7.2.1.2.1.5

Cookies

Module

implement cookies in your own page, see the HTTP2 Cookies topic ( see page 243).

Description

Overview

This section describes how to use the cookie demo in the TCP/IP Demo App HTTP2 demo. For information about how to

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

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 ( see page

236), GET ( see page 238), and cookie ( see page 243) 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 ( see page 226) 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 ( see page

247)

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.

void

HTTPPrint_cookiename(

void

)

{

BYTE *ptr;

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

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

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

7.2.1.2.1.6

Functions

Name Description

HTTPPostImage ( see page

95)

This is function HTTPPostImage.

HTTPPostConfig ( see page 95)

Processes the configuration form on config/index.htm

This is function HTTPPostSNMPCommunity.

HTTPPostSNMPCommunity

( see page 96)

HTTPPostDDNSConfig ( see page 96)

HTTPPostEmail ( see page

96)

Parsing and collecting http data received from http form.

Processes the e-mail form on email/index.htm

HTTPPostLCD ( see page

HTTPPostMD5 ( see page

Processes the LCD form on forms.htm

Processes the file upload form on upload.htm

Module

HTTP_IO_RESULT HTTPPostImage();

7.2.1.2.1.6.1

HTTPPostImage Function

File

CustomHTTPApp.c

C static

Description

This is function HTTPPostImage.

7.2.1.2.1.6.2

HTTPPostConfig Function

File

CustomHTTPApp.c

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

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

Return Values

HTTP_IO_DONE

HTTP_IO_NEED_DATA

Description

all parameters have been processed data needed by this function has not yet arrived

7.2.1.2.1.6.3

HTTPPostSNMPCommunity Function

File

CustomHTTPApp.c

C static

HTTP_IO_RESULT HTTPPostSNMPCommunity();

Description

This is function HTTPPostSNMPCommunity.

7.2.1.2.1.6.4

HTTPPostDDNSConfig Function

File

CustomHTTPApp.c

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 ( see page 99)) 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 ( see page 245) is loaded.

Return Values

HTTP_IO_DONE

HTTP_IO_NEED_DATA

HTTP_IO_WAITING

Description

Finished with procedure

More data needed to continue, call again later

Waiting for asynchronous process to complete, call again later

7.2.1.2.1.6.5

HTTPPostEmail Function

File

CustomHTTPApp.c

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 plaintext encoding. The third section has headers indicating an attached

7.2 Available Demos Microchip TCP/IP Stack Help Demo App 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

HTTP_IO_DONE

HTTP_IO_WAITING

HTTP_IO_NEED_DATA

Description

the message has been sent the function is waiting for the SMTP process to complete data needed by this function has not yet arrived

7.2.1.2.1.6.6

HTTPPostLCD Function

File

CustomHTTPApp.c

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

HTTP_IO_DONE

HTTP_IO_WAITING

HTTP_IO_NEED_DATA

Section

Function Prototypes and Memory Globalizers

Description

the parameter has been found and saved the function is pausing to continue later data needed by this function has not yet arrived

7.2.1.2.1.6.7

HTTPPostMD5 Function

File

CustomHTTPApp.c

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

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

data is trashed in this process, allowing us to accept ( see page 174) 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

HTTP_IO_DONE

HTTP_IO_WAITING

HTTP_IO_NEED_DATA

Description

all parameters have been processed the function is pausing to continue later data needed by this function has not yet arrived

7.2.1.2.1.7

Variables

Module

ImageUpdate_Addr ( see page 98)

Variables

Name

Flag_ImageUpdate_running

( see page 98)

Description

This is variable Flag_ImageUpdate_running.

Processes the file upload form on upload_Image.htm

DDNSData ( see page 99)

RAM allocated for DDNS parameters

ImageUpdate_Checksum ( see page 99)

This is variable ImageUpdate_Checksum.

ImageUpdate_Size ( see page 99) lastFailure ( see page 99)

This is variable ImageUpdate_Size.

Stick status message variable. See lastSuccess ( see page 100) for details.

lastSuccess ( see page 100) Sticky status message variable. This is used to indicated whether or not the

7.2.1.2.1.7.1

Flag_ImageUpdate_running Variable

File

CustomHTTPApp.c

UINT8 Flag_ImageUpdate_running = 0;

Description

This is variable Flag_ImageUpdate_running.

7.2.1.2.1.7.2

ImageUpdate_Addr Variable

File

CustomHTTPApp.c

UINT32 ImageUpdate_Addr = 0;

Description

This function demonstrates the processing of file uploads. First, the function locates the file data, skipping over any headers

7.2 Available Demos Microchip TCP/IP Stack Help Demo App 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 update. 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 ( see page 174) 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 ~uploadeImage~ callback reads this data later to send back to the client.

Preconditions

None

Return Values

HTTP_IO_DONE

HTTP_IO_WAITING

HTTP_IO_NEED_DATA

Description

all parameters have been processed the function is pausing to continue later data needed by this function has not yet arrived

7.2.1.2.1.7.3

DDNSData Variable

File

CustomHTTPApp.c

BYTE DDNSData[100];

Description

RAM allocated for DDNS parameters

7.2.1.2.1.7.4

ImageUpdate_Checksum Variable

File

CustomHTTPApp.c

UINT32 ImageUpdate_Checksum = 0;

Description

This is variable ImageUpdate_Checksum.

7.2.1.2.1.7.5

ImageUpdate_Size Variable

File

CustomHTTPApp.c

UINT32 ImageUpdate_Size = 0;

Description

This is variable ImageUpdate_Size.

7.2.1.2.1.7.6

lastFailure Variable

File

CustomHTTPApp.c

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

BOOL lastFailure = FALSE;

Description

Stick status message variable. See lastSuccess ( see page 100) for details.

7.2.1.2.1.7.7

lastSuccess Variable

File

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

7.2.1.2.2

E-mail (SMTP) Demo

Functions

Name

SMTPDemo ( see page

101)

Description

Demonstrates use of the e-mail (SMTP) client.

Description

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 ( see page 96). 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 ( see page 101)() function.

1. Replace ( see page 226) the initializer of the RAMStringTo[] array with the target email address.

2. Replace ( see page 226) 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 ( see page 96) 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 ( see page 101) 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

100

7.2 Available Demos Microchip TCP/IP Stack Help Demo App 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 ( see page 309) 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 ( see page 310)) 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.

7.2.1.2.2.1

SMTPDemo Function

File

MainDemo.h

C void

SMTPDemo();

Module

E-mail (SMTP) Demo ( see page 100)

Returns

None

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 ( see page 96) in

CustomHTTPApp.c.

Preconditions

The SMTP client is initialized.

7.2.1.2.3

Generic TCP Client

Functions

Name

GenericTCPClient ( see page 102)

Description

Implements a simple HTTP client (over TCP).

Variables

Name

RemoteURL ( see page

ServerName ( see page

ServerPort ( see page 103) Note that if HTTPS is used, the ServerName ( see page 103) and URL must

Description

Defines the URL to be requested by this HTTP client

Defines the server to be accessed for this application

change to an SSL enabled server.

101

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

Description

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 ( see page 157). This

socket will use a TCP_PURPOSE_GENERIC_TCP_CLIENT socket type ( see page 157) from the TCP socket structure ( see page 158) 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 ( see page 174) 125 bytes of data and then use an HTTP GET ( see page 238) 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.

7.2.1.2.3.1

GenericTCPClient Function

File

MainDemo.h

C void

GenericTCPClient();

Module

Generic TCP Client ( see page 101)

Returns

None

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.

102

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

Preconditions

TCP is initialized.

7.2.1.2.3.2

Variables

Module

Generic TCP Client ( see page 101)

Variables

Name

RemoteURL ( see page

Description

Defines the URL to be requested by this HTTP client

ServerName ( see page

ServerPort ( see page 103) Note that if HTTPS is used, the ServerName ( see page 103) and URL must

Defines the server to be accessed for this application

change to an SSL enabled server.

7.2.1.2.3.2.1

RemoteURL Variable

File

GenericTCPClient.c

ROM BYTE RemoteURL[] = "/search?as_q=Microchip&as_sitesearch=microchip.com";

Description

Defines the URL to be requested by this HTTP client

7.2.1.2.3.2.2

ServerName Variable

File

GenericTCPClient.c

BYTE ServerName[] = "www.google.com";

Description

Defines the server to be accessed for this application

7.2.1.2.3.2.3

ServerPort Variable

File

GenericTCPClient.c

WORD ServerPort = HTTP_PORT;

Description

Note that if HTTPS is used, the ServerName ( see page 103) and URL must change to an SSL enabled server.

103

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

7.2.1.2.4

Generic TCP Server

Functions

Name

GenericTCPServer ( see page 105)

Description

Implements a simple ToUpper TCP Server.

Macros

Name

SERVER_PORT ( see page 105)

Description

Defines which port the server will listen ( see page 180) on

Description

Overview

The Generic TCP Server example demonstrates how to build a TCP server application. Once you connect ( see page 176)

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 ( see page 160) 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 ( see page 105) demo implements a task function with 3 states. In the first state, SM_HOME, the

task will attempt to open a TCP server

socket ( see page 157).

This socket will use a

TCP_PURPOSE_GENERIC_TCP_SERVER socket type ( see page 157) from the TCP socket structure ( see page 158)

that was initialized in your configuration files. It will also listen ( see page 180) on TCP port 9760 (defined by the macro

SERVER_PORT ( see page 105)).

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 ( see page 180) for new connections.

104

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

7.2.1.2.4.1

GenericTCPServer Function

File

MainDemo.h

C void

GenericTCPServer();

Module

Generic TCP Server ( see page 104)

Returns

None

Description

This function implements a simple TCP server. The function is invoked periodically by the stack to listen ( see page 180)

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.

7.2.1.2.4.2

Macros

Name

SERVER_PORT ( see page 105)

Module

Generic TCP Server ( see page 104)

Description

Defines which port the server will listen ( see page 180) on

7.2.1.2.4.2.1

SERVER_PORT Macro

File

GenericTCPServer.c

#define

SERVER_PORT 9760

Description

Defines which port the server will listen ( see page 180) on

7.2.1.2.5

Ping (ICMP) Demo

Functions

Name Description

PingDemo ( see page 106)

Demonstrates use of the ICMP (Ping) client.

Macros

Name

HOST_TO_PING ( see page 107)

Description

Address ( see page 152) 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.

105

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

Description

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 ( see page 106) 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 ( see page 269) 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 ( see page 271) callback function and take

action depending on the return value:

Value Action

-2 Remain in this state and keep waiting for a response.

-1

-3

Write a message to the LCD indicating that the ping timed out. Change state to SM_HOME.

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.

7.2.1.2.5.1

PingDemo Function

File

MainDemo.h

C void

PingDemo();

Module

Ping (ICMP) Demo ( see page 105)

Returns

None

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.

106

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

7.2.1.2.5.2

Macros

Name

HOST_TO_PING ( see page 107)

Description

Address ( see page 152) 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 ( see page 105)

7.2.1.2.5.2.1

HOST_TO_PING Macro

File

PingDemo.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 ( see page 152) 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.

7.2.1.2.6

SNMP Server (Agent)

Functions

Name

SendNotification ( see page

119)

SNMPGetTimeStamp ( see page 120)

Description

Prepare, validate remote node which will receive trap and send trap pdu.

Obtains the current Tick value for the SNMP time stamp.

Macros

Name Description

MAX_TRY_TO_SEND_TRAP ( see page 121)

SNMP_MAX_NON_REC_ID_OID

( see page 122)

Update the Non record id OID value which is part of CustomSnmpDemo.c file

STACK_USE_SMIV2 ( see page 122)

Default STACK_USE_SMIV2 is enabled . For Stack V5.31,

STACK_USE_SMIV2 should be disabled.

Variables

Name

gSendTrapSMstate ( see page 120)

gSnmpNonMibRecInfo ( see page 121) gSnmpv3UserSecurityName

( see page 121)

Description

This is variable gSendTrapSMstate.

OLD snmp.mib file with SMIv1 standard

This is variable gSnmpv3UserSecurityName.

Description

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

107

7.2 Available Demos Microchip TCP/IP Stack Help Demo App is added with TCPIP Stack Version 5.31. SNMPv1 and V2c are enabled with single macro

#define

STACK_USE_SNMP_SERVER . The SNMPv3 server could be selectively enabled with independent macro #define

STACK_USE_SNMPV3_SERVER

. As SNMPv3 stacks are required to support SNMPv1 and SNMPv2c, enabling the SNMPv3

Server will automatically enable SNMPv1 and SNMPv2c servers in the Microchip TCPIP Stack SNMP agent. These macros are defined in the

TCPIP (MAC/PHY).h

file located at

<Installation Path>:\Microchip Solutions

MAIN\TCPIP\Demo App\Configs\ .

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, and 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.

Note that even though SNMPv3 also requires SNMPv1 and SNMPv2c, a layer in the SNMP stack will prevent access to the variables that should be secured by SNMPv3. SNMP variables are structures in a tree in the Management Information Base

(MIB). Access to parts of this tree are determined by version. For example, SYSTEM-type variables can be accessed regardless of SNMP version, SNMPv2c requests can access part of the tree, and authenticated SNMPv3 requests can access the complete tree.

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.

7.2.1.2.6.1

MIB Files

Module

Description

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

108

7.2 Available Demos Microchip TCP/IP Stack Help Demo App 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.

7.2.1.2.6.2

MIB Browsers

Module

• The TCP/IP Configuration Wizard ( see page 64) can be used to configure the default SNMP community names. At

Description

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.

109

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

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

110

7.2 Available Demos Microchip TCP/IP Stack Help Demo App requesting the "public" community.

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 ( see page 91) 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.

USM User

Security Level

USER 1

microchip auth, priv

USER 2

SnmpAdmin auth, no priv

USER 3

root no auth, no priv

Auth Algorithm

Auth password

Privacy Algorithm

Privacy password

MD5 auth12345

AES priv12345

SHA1

ChandlerUS

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.

111

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

• 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 ( see page 152) 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."

7.2.1.2.6.3

SNMP Operations

Module

Description

Get

112

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

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

113

7.2 Available Demos Microchip TCP/IP Stack Help Demo App 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.

7.2.1.2.6.4

SNMP Traps

Module

The current implementation of the V2c agent also generates a standard "Authentication ( see page 91) Failure Trap":

114

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

Description

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.

Several preprocessor macro in the

TCPIPConfig.h

variant header file can be used to enable or disable traps in the agent.

Commenting and un-commenting these macros in the file will have different effects. The SNMP_TRAP_DISABLED macro will disable traps entirely if it is not commented:

#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:

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

To enable traps in SNMPv3, the

#define SNMP_V1_V2_TRAP_WITH_SNMPv3

macro must be uncommented.

The following table illustrates how to enable/disable traps for different versions of SNMP:

TRAP v1

(Enabled by default)

SNMPv1

• Comment out the

#define

SNMP_TRAP_DISABLED macro

SNMPv2c

• Comment out the

#define

SNMP_TRAP_DISABLED macro

SNMPv3

• Comment out the macro

#define

SNMP_TRAP_DISABLED macro

• Uncomment the

#define

SNMP_V1_V2_TRAP_WITH_SNMPV3

TRAP v2

(Disabled by default)

(Not supported)

• Comment out the macro

#define

SNMP_TRAP_DISABLED

• Uncomment the

#define

SNMP_STACK_USE_V2_TRAP macro

• Comment out the #define

SNMP_TRAP_DISABLED

macro

• Uncomment the

#define

SNMP_V1_V2_TRAP_WITH_SNMPV3 macro

• Uncomment the #define

SNMP_STACK_USE_V2_TRAP

macro

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

115

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

'trapReceiverIPAddress.'

• If Button 3 on the demo board is pressed, an organization-specific PUSH_BUTTON trap will be sent.

• 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 ( see page 91) 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.

116

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

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 ( see page

91) 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:

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.

117

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

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

7.2.1.2.6.5

HTTP Configuration

Module

SendNotification ( see page

Description

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.

118

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

7.2.1.2.6.6

Functions

Name

119)

SNMPGetTimeStamp ( see page 120)

Description

Prepare, validate remote node which will receive trap and send trap pdu.

Obtains the current Tick value for the SNMP time stamp.

Module

7.2.1.2.6.6.1

SendNotification Function

File

CustomSNMPApp.c

C static

BOOL SendNotification(

BYTE receiverIndex,

This function retrieves the absolute time measurements for SNMP time stamp.Use TickGet ( see page 609) and

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.

Remarks

None.

Preconditions

SNMPTrapDemo() is called.

Parameters

receiverIndex var

Description

The index to array where remote ip address is stored.

SNMP var ID that is to be used in notification

119

7.2 Available Demos Microchip TCP/IP Stack Help Demo App val targetIndex

Return Values

TRUE

FALSE

Value of var. Only value of BYTE, WORD or DWORD can be sent.

snmpv3 target index

Description

If notification send is successful.

If send notification failed.

7.2.1.2.6.6.2

SNMPGetTimeStamp Function

File

CustomSNMPApp.c

C static

DWORD SNMPGetTimeStamp();

Description

TickGetDiv64K ( see page 610) to collect all 48bits of the internal Tick Timer.

Remarks

None.

Preconditions

None

Return Values

timeStamp

Description

DWORD timevalue

7.2.1.2.6.7

Variables

Module

gSendTrapSMstate ( see page 120)

Variables

Name

gSnmpNonMibRecInfo ( see page 121) gSnmpv3UserSecurityName

( see page 121)

Description

This is variable gSendTrapSMstate.

OLD snmp.mib file with SMIv1 standard

This is variable gSnmpv3UserSecurityName.

7.2.1.2.6.7.1

gSendTrapSMstate Variable

File

CustomSNMPApp.c

UINT8 gSendTrapSMstate = 0;

Description

This is variable gSendTrapSMstate.

120

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

7.2.1.2.6.7.2

gSnmpNonMibRecInfo Variable

File

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

7.2.1.2.6.7.3

gSnmpv3UserSecurityName Variable

File

CustomSNMPApp.c

BYTE gSnmpv3UserSecurityName[SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE];

Description

This is variable gSnmpv3UserSecurityName.

7.2.1.2.6.8

Macros

Name Description

MAX_TRY_TO_SEND_TRAP ( see page 121)

SNMP_MAX_NON_REC_ID_OID

( see page 122)

Update the Non record id OID value which is part of CustomSnmpDemo.c file

STACK_USE_SMIV2 ( see page 122)

Default STACK_USE_SMIV2 is enabled . For Stack V5.31,

STACK_USE_SMIV2 should be disabled.

Module

addresses and host names of all devices with the Announce ( see page 160) Protocol enabled on your network. You

7.2.1.2.6.8.1

MAX_TRY_TO_SEND_TRAP Macro

File

CustomSNMPApp.c

#define

MAX_TRY_TO_SEND_TRAP (10)

Section

Global Variables

************************************************************************

This Macro is used to provide maximum try for a failure Trap server address

121

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

7.2.1.2.6.8.2

SNMP_MAX_NON_REC_ID_OID Macro

File

CustomSNMPApp.c

#define

SNMP_MAX_NON_REC_ID_OID 3

Description

Update the Non record id OID value which is part of CustomSnmpDemo.c file

7.2.1.2.6.8.3

STACK_USE_SMIV2 Macro

File

CustomSNMPApp.c

#define

STACK_USE_SMIV2

Description

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

7.2.1.2.7

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

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

'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

6. As you type characters in the command prompt, they will be transmitted over the Telnet ( see page 577) TCP port to the

122

7.2 Available Demos Microchip TCP/IP Stack Help Demo App

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 ( see page 577) session.

7.2.1.2.8

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 / MRF24WG0M 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 ( see page 176) 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 ( see page 176) 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

123

7.2 Available Demos Microchip TCP/IP Stack Help Internet Bootloader 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.

7.2.2

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

7.2.2.1

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

124

7.2 Available Demos Microchip TCP/IP Stack Help Internet Bootloader 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 ( see page 322) module which can perform the above procedure upon detection of a TFTP packet. When the Reboot ( see page 322) 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.

125

7.2 Available Demos Microchip TCP/IP Stack Help Internet Bootloader

**: 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.

126

7.2 Available Demos Microchip TCP/IP Stack Help Internet Bootloader

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.

7.2.2.2

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 ( see page 152): 192.168.97.60

• MAC Address ( see page 152): 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 ( see page 322) 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.

127

7.2 Available Demos Microchip TCP/IP Stack Help Internet Bootloader

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

128

7.2 Available Demos Microchip TCP/IP Stack Help Internet Radio 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 ( see page 322) 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.

7.2.3

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 ( view )

2. TCP/IP Networking Part 2: Web-Based Control ( view )

3. TCP/IP Networking Part 3: Advanced Web-Based Control ( view )

129

7.2 Available Demos Microchip TCP/IP Stack Help WiFi Console

7.2.4

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 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 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 ( see page

176) 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 ( see page 176) 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.

130

7.2 Available Demos Microchip TCP/IP Stack Help WiFi Console

7.2.5

WiFi Console

The TCPIP WiFi Console Demo App (previously the TCPIP WiFi Iperf Demo App) is a command line interface (CLI) to the

MRF24WB0M / MRF24WG0M. 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.

The following network types are supported

• CFG_WF_INFRASTRUCTURE (as a client in infrastructure network)

• CFG_WF_ADHOC

• CFG_WF_P2P (Wi-Fi Direct) (as a group client in Wi-Fi Direct network)

CFG_WF_P2P is only available for MRF24WG0MA/B.

New security modes are supported.

• WF_SECURITY_WPS_PUSH_BUTTON (supported by MRF24WG0M only)

• WF_SECURITY_WPS_PIN (supported by MRF24WG0M only)

Wireless configurations are set up in WF_Config.h

New demo feature: Cloud Networking Application

From MLA v5.42.06 March 2013 and future releases, a new demo is added to showcase cloud networking. The relevant source file is CloudTCPClient.c. Reference web server is http://www.openwificloud.com

This cloud demo supports the functions

• Temperature reading

• Potentiometer reading

• LEDs ON/OFF toggling

7.2.5.1

Standalone Commands

These command line interface (CLI) commands are not related to the wireless or networking interface directly.

help

Lists all the available CLI commands for the MRF24WB0M / MRF24WG0M.

getwfver

Lists the WiFi firmware and host driver version numbers.

reset

Issues a host reset.

cls

Resets the prompt.

131

7.2 Available Demos iperf kill iperf ping

Microchip TCP/IP Stack Help WiFi Console

Initiates an iperf session. See the section on iperf ( see page 136) for more information.

Stops a running iperf session. See the section on iperf ( see page 136) for more information.

Initiates a ping session. This will verify IP-level connectivity to another TCP/IP terminal by sending

Internet Control Message Protocol (ICMP) Echo Request messages. The receipt of corresponding

Echo Reply messages are displayed, along with round-trip times.

killping wpscred

Stops a running ping session.

Display WPS credentials.

7.2.5.2

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:

132

7.2 Available Demos Microchip TCP/IP Stack Help iwconfig [ ssid <name> ]

[ mode <idle|managed|adhoc> ]

[ channel <channel list|all> ]

[ power <reenable|disable|unicast|all> ]

[ domain <name> ]

[ rts <length> ]

[ scan ]

[ hibernate ]

[ wakeup ]

Note: iwconfig with no options will display wireless status. ssid name 1-32 ASCII characters.

Currently doesn't accept ( see page 174) spaces in the SSID name.

mode idle managed adhoc

WiFi Console

Forces the MRF24WB0M / MRF24WG0M to disconnect from any currently connected network

(adhoc or infrastructure).

The MRF24WB0M / MRF24WG0M will connect ( see page 176) to the SSID in infrastructure

mode. Note that all the network parameters must be correct before this command is called.

The MRF24WB0M / MRF24WG0M will connect ( see page 176) to the SSID in adhoc mode.

Note that all the network parameters must be correct before this command is called.

channel channel list all power reenable / all disable unicast

A comma separated list of all the channels to scan.

Sets the MRF24WB0M / MRF24WG0M to scan all channels in the given regulatory domain.

Enables all power saving features (PS_POLL) of the MRF24WB0M / MRF24WG0M.

MRF24WB0M / MRF24WG0M will wake up to check for all types of traffic (unicast, multicast, and broadcast).

Disables any power savings features. The MRF24WB0M / MRF24WG0M will always be in an active power state.

The MRF24WB0M / MRF24WG0M will be in it's deepest sleep state, only waking up at periodic intervals to check for unicast data. The MRF24WB0M / MRF24WG0M will not wake up on the

DTIM period for broadcast or multicast traffic.

domain fcc ic etsi spain france japan japana japanb

United States channels 1-11.

Canada channels 1-11. Applicable for MRF24WB0M only.

European channels 1-13.

Spanish channels 10-11. Applicable for MRF24WB0M only.

French channels 10-13. Applicable for MRF24WB0M only.

Japanese channel 1-14. Applicable for MRF24WG0M only.

Japanese channel 14. Applicable for MRF24WB0M only.

Japanese channels 1-11. Applicable for MRF24WB0M only.

133

7.2 Available Demos Microchip TCP/IP Stack Help WiFi Console rts length Set the requested number of bytes to send. Default max is 2347.

scan

Instructs the MRF24WB0M / MRF24WG0M to perform an active site scan. Scan results will be displayed to the output terminal.

hibernate

Turns off LDO of the MRF24W module, which is equivalent to removing power to the

MRF24WB0M / MRF24WG0M. Has the same effect of resetting MRF24WB0M / MRF24WG0M.

MRF24W state is not maintained when transitioning to hibernate mode.

wakeup

Restores power to the MRF24WB0M / MRF24WG0M and reconnects.

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

7.2.5.3

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 / MRF24WG0M 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.

134

7.2 Available Demos auto-dhcp start drop

Microchip TCP/IP Stack Help WiFi Console

Starts the DHCP client.

Only valid if the DHCP module has been compiled in. DHCP client is started by default.

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.

7.2.5.4

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 wep wpa-psk wpa-phrase

The MRF24WB0M / MRF24WG0M will not use any encryption to connect ( see page 176) to the

specified network.

The MRF24WB0M / MRF24WG0M will use either WEP-40 (short) or WEP-104 (long) encryption

to connect ( see page 176) to the specified network.

The MRF24WB0M / MRF24WG0M will use the specified 32-byte PSK to connect ( see page

176) to the WPA/WPA2 network.

The MRF24WB0M / MRF24WG0M 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] value

Instructs the MRF24WB0M / MRF24WG0M 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.

If value is specified, this will instruct the MRF24WB0M / MRF24WG0M 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.

135

7.2 Available Demos psk value

Microchip TCP/IP Stack Help WiFi Console

32-byte hex value for the PSK.

This value can be calculated from the following website hosted on the 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.

7.2.5.5

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

-c <IP addr>

-u

-i <sec>

-b <bandwidth>

-t <time>

Runs the iperf server. No IP address needs to be specified.

Runs the iperf client. The IP address is the IP address of the server.

Server side only. Sends UDP datagrams.

Specified the time interval, in seconds, that the display will be updated.

Specifies the amount of data to try and send. This option is only valid with UDP datagrams.

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 / MRF24WG0M receiver performance. If you start the iperf server on a PC, then you will be measuring MRF24WB0M / MRF24WG0M transmit performance. Below are two images that show receiver and transmitter performance, respectively.

136

7.2 Available Demos Microchip TCP/IP Stack Help WiFi EZConfig

137

7.2 Available Demos Microchip TCP/IP Stack Help WiFi EZConfig

7.2.6

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 ( see page 176) 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 ( see page 176) 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 ( see page 176) 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 ( see page 176) 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.

The following network types are supported

• CFG_WF_ADHOC

• CFG_WF_SOFT_AP

Wireless configurations are set up in WF_Config.h

Adhoc Networks

Upon starting the demo, the network will either connect ( see page 176) 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 / MRF24WG0M 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.

SoftAP Networks

This is only available for MRF24WG0MA/B. Upon starting the demo, the MRF24WG0MA/B will start up a network as a

138

7.2 Available Demos Microchip TCP/IP Stack Help WiFi EZConfig

software-enabled access point (AP), acting as the centralized coordinator for the network. Devices can connect ( see page

176) to the MRF24WG0MA/B softAP. Depending on the RF module firmware version, either 1 or 4 clients can be connected

to the softAP. Routing is not supported. The demo can start a softAP network with no or WEP security.

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

SSID

Security Type

Either adhoc or infrastructure

Name of network (1-32 ASCII characters)

• 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

EZ_CONFIG_SCAN

EZ_CONFIG_STORE

EZ_CONFIG_STALL

The top level define to enable EasyConfig features.

Adds additional ability to instruct the MRF24WB0M / MRF24WG0M module to scan for available networks nearby. This can be done when you are already connected to a network.

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.

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 ( see page 176) to a new network.

EZ_CONFIG_SCAN

The MRF24WB0M / MRF24WG0M 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 / MRF24WG0M 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.

139

7.2 Available Demos Microchip TCP/IP Stack Help Google PowerMeter

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 / MRF24WG0M 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.

New demo feature: Mobile Application

From MLA v5.42.06 March 2013 and future releases, a new mobile application demo is added to Explorer16+PIC32 configuration. The relevant source file is MobileTCPServer.c. Supported devices run on Android (version 4.0 or later) and iOS6 or later. On Goggle Play store and Apple Apps Store, search for the app "OpenWifiFog".

The functions supported

• Temperature reading

• Potentiometer reading

• LEDs ON/OFF toggling

7.2.7

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.

140

7.2 Available Demos Microchip TCP/IP Stack Help Energy Monitoring

7.2.8

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 www.microchip.com/mla .

7.2.9

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

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 http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1406&dDocName=en550456

from:

141

Required Files Microchip TCP/IP Stack Help 8.2 How the Stack Works

Using the Stack

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

8.1

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 ( see page 63) used with the stack.

8.2

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.

8.2.1

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 ( see page 143)- 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 ( see page 147) 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.

142

8.2 How the Stack Works Microchip TCP/IP Stack Help Main File

•

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 ( see page 155) topic in the Protocol Configuration ( see page 154) topic.

8.2.2

APP_CONFIG Structure

Most of the stack-related application variables are stored in an APP_CONFIG structure. These include addresses ( see page 152), 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.

8.2.3

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.

8.2.3.1

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 ( see page 610)() 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 ( see page 289)() function will need to initialize an SPI port to communicate to a

memory storage ( see page 147) 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 ( see page 143) 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 ( see page 559)() for the

TCP protocol, HTTPInit ( see page 255)() for HTTP2,...). After StackInit() has been called, you can call other

application-specific firmware initialization functions.

8.2.3.2

Main Loop

Once your program has been initialized, you should enter an infinite loop which will handle your application tasks. Within this

143

8.2 How the Stack Works Microchip TCP/IP Stack Help Cooperative Multitasking 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 ( see page 256)

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.

8.2.4

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.

unsigned char

gAppState;

// State tracking variable

int

main (

void

)

{

144

8.2 How the Stack Works Microchip TCP/IP Stack Help Cooperative Multitasking

// 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:

(ButtonPressDetected (BUTTON_1) )

// Check an input

gAppState = STATE_MONITOR_MACHINERY;

break

;

case

STATE_MONITOR_MACHINERY:

LCDDisplay (stringTransferringData);

// Generate or send data

(DataBufferIsFull())

{

TransferData();

}

else

{

SampleData();

}

(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 ( see page 609)

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 ( see page 609)

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

145

8.2 How the Stack Works Microchip TCP/IP Stack Help RTOS

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 ( see page 608) defines the number of ticks in a second, TICK_MINUTE ( see page 608) defines the number of ticks in a minute, and TICK_HOUR ( see page

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

8.2.5

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 Application Note 1264 on the Microchip web site.

146

External Storage Microchip TCP/IP Stack Help 9.1 Hardware Configuration

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.

9.1

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 ( see page 84).

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.

9.1.1

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

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

9.1.2

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 ( see page 276) 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

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

147

9.1 Hardware Configuration Microchip TCP/IP Stack Help ENC28J60 Config 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 ( see page 157) (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

xxxxxx_CS_IO

Purpose Sample Value

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 xxxxxx_SDI_TRIS

Defines the TRIS bit that corresponds to the chip select pin on the device.

xxxxxx_SCK_TRIS Defines the TRIS bit that corresponds to the clock pin of the SPI module connected to the device.

TRISGbits.TRISG6

Defines the TRIS bit that corresponds to the data-in pin of the SPI module connected to the device.

TRISDbits.TRISD12

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 xxxxxx_SSPBUF

Points to the interrupt flag for the SPI module connected to the device.

Points to the SPI buffer register for the SPI module connected to the device.

IFS2bits.SPI2IF

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

9.1.3

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

148

9.1 Hardware Configuration Microchip TCP/IP Stack Help ENCX24J600 Config

#define ENC_CS_TRIS xxxxxxxxxxxxxxx

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

Macro

ENC_CS_IO

Purpose Sample Value

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

Defines the TRIS bit that corresponds to the chip select pin.

TRISDbits.TRISD14

ENC_CS_TRIS

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

ENC_SSPBUF

Points to the interrupt flag for the SPI module connected to the chip.

Points to the SPI buffer register for the SPI module connected to the chip.

IFS0bits.SPI1IF

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

9.1.4

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

#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

8-bit demultiplexed PSP Mode 1 with RD and WR pins

8-bit demultiplexed PSP Mode 2 with R/~W and EN pins

16-bit demultiplexed PSP Mode 3 with Rd, WRL, and WRH pins

16-bit demultiplexed PSP Mode 4 with R/~W, B0SEL, and B1SEL pins

8-bit multiplexed PSP Mode 5 with RD and WR pins

8-bit multiplexed PSP Mode 6 with R/~W and EN pins

16-bit multiplexed PSP Mode 9 with AL, RD, WRL, and WRH pins

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

149

9.1 Hardware Configuration Microchip TCP/IP Stack Help ENCX24J600 Config

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

ENC100_INTERFACE_MODE

ENC100_PSP_USE_INDIRECT_-

RAM_ADDRESSING

ENC100_TRANSLATE_TO_PIN-

_ADDR(a)

ENC100_MDIX_IO

ENC100_MDIX_TRIS

ENC100_INT_IO

ENC100_INT_TRIS

ENC100_CS_IO

Purpose Sample Value

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.

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

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

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

Defines the TRIS bit to use for the Auto-crossover circuit.

TRISBbits.TRISB3

Defines an I/O pin to use for the chip’s interrupt signal pin.

This feature is currently unused by the stack.

PORTAbits.RA13

Defines a TRIS bit to use for the chip’s interrupt signal pin.

TRISAbits.TRISA13

Defines a port bit for use with the chip select pin. Optional in

PSP modes.

LATAbits.LATA5

ENC100_CS_TRIS

ENC100_POR_IO

ENC100_SCK_AL_IO

Defines a TRIS bit to use for the chip select pin.

TRISAbits.TRISA5

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

Defines the TRIS bit to use with a power disconnect circuit.

TRISCbits.TRISC1

ENC100_POR_TRIS

ENC100_SO_WR_B0SEL_EN_IO

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

Defines the TRIS bit to use with the ENC100_SI_RD_RW_IO pin.

TRISDbits.TRISD5

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

ENC100_ISR_ENABLE

Defines the TRIS bit to use with the ENC100_SCK_AL_IO pin.

TRISDbits.TRISD15

Points to the bit to enable the interrupt for the I/O based

ENCX24J600-triggered interrupt. This feature is not currently implemented.

IEC1bits.INT2IE

150

9.1 Hardware Configuration

ENC100_ISR_FLAG

ENC100_ISR_POLARITY

ENC100_ISR_PRIORITY

ENC100_SPI_ENABLE

ENC100_SPI_IF

ENC100_SSPBUF

ENC100_SPISTAT

ENC100_SPISTATbits

ENC100_SPICON1

ENC100_SPICON1bits

ENC100_SPICON2

ENC100_SPIBRG

Microchip TCP/IP Stack Help PIC32MX7XX Config

Points to the interrupt flag bit for the I/O based

ENCX24J600-triggered interrupt. This feature is not currently implemented.

IFS1bits.INT2IF

Points to the interrupt polarity bit for the I/O based

ENCX24J600-triggered interrupt. This feature is not currently implemented.

INTCON2bits.INT2EP

Points to the interrupt priority bit for the I/O based

ENCX24J600-triggered interrupt. This feature is not currently implemented.

IPC7bits.INT2IP

Points to the SPI module enable bit if SPI mode is used.

SPI1STATbits.SPIEN

Points to the interrupt flag for the SPI module if SPI mode is used.

IFS0bits.SPI1IF

Points to the SPI buffer register for the SPI module if SPI mode is used.

SPI1BUF

Points to the SPI status register for the SPI module if SPI mode is used.

SPI1STAT

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

Points to the SPI control register for the SPI module if SPI mode is used.

SPI1CON1

Provides bitwise access to the SPI control register for the

SPI module if SPI mode is used (see ENC_SPISTATbits entry).

SPI1CON1bits

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

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

9.1.5

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.

9.1.6

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

151

9.2 Address Microchip TCP/IP Stack Help MAC Address

Macro

PHY_RMII

Purpose

Define this macro if the external PHY runs in RMII mode. Comment it out if you’re using an MII PHY.

Sample

Value

PHY_CONFIG_ALTERNATE Define this symbol if the PIC32MX7XX uses the alternate configuration pins to

connect ( see page 176) 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

ETH_CFG_LINK

ETH_CFG_AUTO

ETH_CFG_10

ETH_CFG_100

Purpose

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.

Sample

Value

Set to 1 to use auto negotiation. Strongly recommended.

Use/advertise 10 Mbps capability.

Use/advertise 100 Mbps capability.

ETH_CFG_HDUPLEX

ETH_CFG_FDUPLEX

Use/advertise half duplex capability.

Use/advertise full duplex capability.

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.

9.2

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.

9.2.1

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

MY_DEFAULT_MAC_BYTE1

MY_DEFAULT_MAC_BYTE2

MY_DEFAULT_MAC_BYTE3

MY_DEFAULT_MAC_BYTE4

Sample Value

(0x00)

(0x04)

(0xA3)

(0x00)

152

9.2 Address Microchip TCP/IP Stack Help IP Address

MY_DEFAULT_MAC_BYTE5

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, MRF24WG0M 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 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 ( see page 143) initialization code so it will obtain the

device's MAC address from one of these EEPROMs instead of the default MAC address macros.

9.2.2

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

MY_DEFAULT_IP_ADDR_BYTE1

MY_DEFAULT_IP_ADDR_BYTE2

MY_DEFAULT_IP_ADDR_BYTE3

MY_DEFAULT_IP_ADDR_BYTE4

MY_DEFAULT_MASK_BYTE1

MY_DEFAULT_MASK_BYTE2

MY_DEFAULT_MASK_BYTE3

MY_DEFAULT_MASK_BYTE4

MY_DEFAULT_GATE_BYTE1

Property

Default IP address byte 1

Default IP address byte 2

Default IP address byte 3

Default IP address byte 4

Default subnet mask byte 1

Default subnet mask byte 2

Default subnet mask byte 3

Default subnet mask byte 4

Default gateway byte 1

Default gateway byte 2

Default gateway byte 3

Default gateway byte 4

255ul

0ul

192ul

168ul

1ul

Sample

Value

192ul

168ul

1ul

100ul

255ul

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 ( see page 143) 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.

153

9.3 Protocol Configuration Microchip TCP/IP Stack Help Protocol Macros and Files

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 ( see page 152) 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.

9.3

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.

154

9.3 Protocol Configuration Microchip TCP/IP Stack Help Protocol Macros and Files

9.3.1

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

ICMP ( see page

268)

STACK_USE_ICMP_SERVER

Function

Provides the ability to query and respond to pings.

Required Files

ICMP.c

ICMP.h

ICMP ( see page

268)

STACK_USE_ICMP_CLIENT Provides the ability to transmit pings.

ICMP.c

ICMP.h

HTTP2 ( see page

235)

STACK_USE_HTTP2_SERVER

FTP

STACK_USE_SSL_SERVER

STACK_USE_SSL_CLIENT

STACK_USE_FTP_SERVER

STACK_USE_SMTP_CLIENT

STACK_USE_SNMP_SERVER

TFTP ( see page

582)

STACK_USE_TFTP_CLIENT

Telnet ( see page

577)

STACK_USE_TELNET_SERVER

Announce

( see page 160)

STACK_USE_ANNOUNCE

Provides HTTP server functionality with

dynamic variables, POST, Cookies ( see

page 93), Authentication ( see page 91),

and other features

HTTP2.c

HTTP2.h

TCP.c, TCP.h,

CustomHTTPApp.c

and

HTTPPrint.h

(see HTTP2 ( see page 235) section for

information on these files)

Provides support for SSL server sockets.

Provides support for SSL client sockets.

SSL.c,

ARCFOUR.c,

Random.h,

RSA.h

SSL.h,

ARCFOUR.h, BigInt.c,

BigInt.h, Random.c,

RSA.c,

SSL.c,

ARCFOUR.c,

SSL.h,

ARCFOUR.h, BigInt.c,

BigInt.h,

Random.h,

RSA.h

Random.c,

RSA.c,

Provides ability to remotely upload MPFS2 images to HTTP2 servers via FTP

FTP.c, FTP.h, TCP.c,

TCP.h

Provides the ability to send email SMTP.c,

TCP.c,

SMTP.h,

TCP.h,

Helpers.c, Helpers.h

Provides a network-based machine control/monitoring protocol

SNMP.c ( see page

454), SNMP.h ( see page 456),

UDP.c,

UDP.h

Provides unreliable file upload/download services

TFTPc.c,

TCP.c, TCP.h

TFTPc.h,

Provides telnet services.

Provides device hostname and IP address discovery on a local Ethernet subnet

Telnet.c,

TCP.c, TCP.h

Announce.c,

Announce.h

Telnet.h,

155

9.3 Protocol Configuration Microchip TCP/IP Stack Help Additional Features

STACK_USE_DNS

STACK_USE_NBNS

Provides the ability to resolve hostnames to

IP addresses

Provides the ability to resolve hostnames to

IP addresses on the same subnet.

DNS.c, DNS.h, UDP.c,

UDP.h

NBNS.c,

UDP.c, UDP.h

NBNS.h,

SNTP ( see page

462)

STACK_USE_SNTP_CLIENT Provides the ability to get the date/time from the internet

SNTP.c,

UDP.c, UDP.h

SNTP.h,

Dynamic

DNS ( see page

198)

STACK_USE_DYNAMICDNS_CLIENT Provides the ability to resolve hostnames to

IP addresses that change frequently.

DynDNS.c, DynDNS.h,

TCP.c, TCP.h

STACK_USE_MPFS2

STACK_USE_TCP

STACK_USE_UDP

Provides MPFS2 services for custom applications. This functionality will be enabled/required automatically by stack-based protocols that require MPFS2.

MPFS2.c, MPFS2.h

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

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

9.3.2

Additional Features

The TCP/IP stack includes some additional functionality that can be enabled in

TCPIPConfig.h

Feature

UART Demo

UART-to-TCP

Bridge

IP Gleaning

Reboot Server ( see page 322)

Macro

STACK_USE_UART

STACK_USE_UART2TCP_BRIDGE

STACK_USE_IP_GLEANING

STACK_USE_REBOOT_SERVER

Description Required Files

Application demo using

UART for IP address display and stack configuration.

UART.c, UART.h

UART to TCP Bridge application example

UART2TCPBridge.c,

UART2TCPBridge.h

Allows assignment of an IP address via reception of an

ICMP packet with a valid IP during configuration mode

Allows the PIC to be reset remotely bootloaders).

(useful for

Reboot.c, Reboot.h

UDP

Performance Test

( see page 298)

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

156

9.3 Protocol Configuration Microchip TCP/IP Stack Help Sockets

TCP

Performance Test

( see page 298)

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 ( see page 172)

STACK_USE_BERKELEY_API

Provides a Berkeley Sockets

( see page 157)

API abstraction layer.

BerkeleyAPI.c,

BerkeleyAPI.h

9.3.3

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.

9.3.3.1

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 ( see page

147)). You can specify the base address in this RAM chip to use with the

TCP_SPI_RAM_BASE_ADDRESS

macro.

9.3.3.2

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

157

9.3 Protocol Configuration Microchip TCP/IP Stack Help Sockets

#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 ( see page 577) 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 ( see page 180) 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 ( see page 546)

and

TCPConnect ( see page 537)

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 ( see page 172) layer (also see BSD Sockets ( see page 159)).

9.3.3.3

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_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_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_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:

158

9.3 Protocol Configuration Microchip TCP/IP Stack Help Sockets

• 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 ( see page 157). 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.

9.3.3.4

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 ( see page 631)

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 ( see page 631)

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

9.3.3.5

BSD Sockets

The Berkeley API socket configuration option ( see page 156) will require Berkeley sockets. Each one of these internally

uses one TCP or UDP socket, defined by the TCPSocketInitializer[] array ( see page 158) and the

MAX_UDP_SOCKETS

( see page 159) 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)

159

Microchip TCP/IP Stack Help Announce Stack Members 10.1 Announce

Stack API

Modules

Name

Announce ( see page 160)

Provides Address ( see page 152) Resolution Protocol support.

Description

Provides a UDP MAC address announcement feature.

Berkeley (BSD) Sockets ( see page 172) Provides a BSD socket wrapper to the Microchip TCP/IP Stack.

DNS Client ( see page 189)

ICMP ( see page 268)

Performance Tests ( see page 298)

Provides Domain Name Service resolution.

Updates an external IP address to a Dynamic DNS service.

Calculates MD5 and SHA-1 hash sums.

Provides several helper function for stack operation.

Provides an advanced embedded web server.

Provides Ping functionality.

Provides a light-weight file system.

NBNS ( see page 295)

Reboot ( see page 322)

The Announce protocol is designed to be used with the TCP/IP Discoverer ( see page 67) PC program.

Describes the NetBIOS Name Service protocol.

Tests TCP and UDP performance of an application.

Sends e-mail messages across the internet.

Provides a service to remotely reboot the PIC.

Provides an Simple Network Management Protocol agent.

Obtains absolute time stamps from a pool of network time servers.

Implements SSL encryption for TCP connections.

Implements the TCP transport layer protocol.

Describes the operation of the Telnet module.

Describes the TFTP module.

Provides accurate time-keeping capabilities.

Implements the UDP transport layer protocol.

Description

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

10.1

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

160

10.1 Announce Microchip TCP/IP Stack Help Announce Stack Members

10.1.1

Announce Stack Members

Functions

Name

AnnounceIP ( see page

161)

DiscoveryTask ( see page

161)

Module

Announce ( see page 160)

Description

Transmits an Announce ( see page 160) packet.

Announce ( see page 160) callback task.

Description

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.

10.1.1.1

AnnounceIP Function

File

Announce.h

C void

AnnounceIP();

Side Effects

None

Returns

None

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.

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.

Preconditions

Stack is initialized()

10.1.1.2

DiscoveryTask Function

File

Announce.h

C void

DiscoveryTask();

161

10.2 ARP Microchip TCP/IP Stack Help ARP Public Members

Side Effects

None

Returns

None

Description

Recurring task used to listen ( see page 180) 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.

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.

Preconditions

Stack is initialized()

10.2

ARP

Types

Name

ARP_PACKET ( see page

171)

Description

ARP packet structure

Description

The Address ( see page 152) 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 ( see page 547) and UDPOpen ( see page 617) 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.

10.2.1

ARP Public Members

Functions

Name

ARPResolve ( see page

163)

ARPIsResolved ( see page

164)

Description

Transmits an ARP request to resolve an IP address.

Determines if an ARP request has been resolved yet.

162

10.2 ARP Microchip TCP/IP Stack Help ARP Public Members

ARPDeRegisterCallbacks ( see page 164)

ARPRegisterCallbacks ( see page 165)

ARPSendPkt ( see page

165)

De-Registering callbacks with ARP module that are registered previously.

Registering callback with ARP module to get notified about certian events.

Transmits an ARP request/Reply initated by Application or external module.

Macros

Name Description

ARP_REQ ( see page 166)

Operation code indicating an ARP Request

ARP_RESP ( see page 166) Operation code indicating an ARP Response

MAX_REG_APPS ( see page 166)

MAX num allowed registrations of Modules/Apps

Module

arp_app_callbacks ( see page 166)

Structures

Name

Description

This is record arp_app_callbacks.

Description

The following functions and variables are available to the stack application.

10.2.1.1

ARPResolve Function

File

ARP.h

C void

ARPResolve(

IP_ADDR* IPAddr

);

Returns

None

Description

This function transmits and ARP request to determine the hardware address of a given IP address.

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 ( see page 164)() function.

Preconditions

None

Parameters

IPAddr

Description

The IP address to be resolved. The address must be specified in network byte order (big endian).

163

10.2 ARP Microchip TCP/IP Stack Help ARP Public Members

10.2.1.2

ARPIsResolved Function

File

ARP.h

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.

Remarks

This function is only required when the stack is a client, and therefore is only enabled when STACK_CLIENT_MODE is enabled.

Preconditions

ARP packet is ready in the MAC buffer.

Parameters

IPAddr

Description

The IP address to be resolved. This must match the IP address provided to the

ARPResolve ( see page 163)() function call.

A buffer to store the corresponding MAC address retrieved from the ARP query.

MACAddr

Return Values

TRUE

FALSE

Description

The IP address has been resolved and MACAddr MAC address field indicates the response.

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 ( see page 163)() 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.

10.2.1.3

ARPDeRegisterCallbacks Function

File

ARP.h

BOOL ARPDeRegisterCallbacks(

CHAR id

);

Returns

TRUE - On success FALSE - Failure to indicate invalid reg_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.

164

10.2 ARP

Preconditions

None

Parameters

reg_id

Microchip TCP/IP Stack Help ARP Public Members

Description

Registration-id returned in ARPRegisterCallbacks ( see page 165) call

10.2.1.4

ARPRegisterCallbacks Function

File

ARP.h

CHAR ARPRegisterCallbacks(

struct

arp_app_callbacks * app

);

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 ( see page 166) and there is no free slot for registration

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 ( see page 152) and IP-address). This is an extension for zeroconf protocol

implementation (ZeroconfLL.c)

Preconditions

None

Parameters

app

Description

ARP-Application callbacks structure supplied by user-application

10.2.1.5

ARPSendPkt Function

File

ARP.h

BOOL ARPSendPkt(

DWORD SrcIPAddr,

DWORD DestIPAddr,

BYTE op_req

);

Returns

TRUE - The ARP packet was generated properly FALSE - Not possible return value

Description

This function transmits and ARP request/reply to determine the hardware address of a given IP address (or) Announce ( see page 160) self-address to all nodes in network. Extended for zeroconf protocol.

Remarks

This API is to give control over AR-packet to external modules.

165

10.2 ARP Microchip TCP/IP Stack Help ARP Public Members

Preconditions

ARP packet is ready in the MAC buffer.

Parameters

SrcIPAddr

DestIPAddr op_req

Description

The Source IP-address

The Destination IP-Address ( see page 152)

Operation Request (ARP_REQ ( see page 166)/ARP_RESP ( see page

166))

10.2.1.6

arp_app_callbacks Structure

File

ARP.h

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.

10.2.1.7

ARP_REQ Macro

File

ARP.h

#define

ARP_REQ 0x0001u

// Operation code indicating an ARP Request

Description

Operation code indicating an ARP Request

10.2.1.8

ARP_RESP Macro

File

ARP.h

#define

ARP_RESP 0x0002u

// Operation code indicating an ARP Response

Description

Operation code indicating an ARP Response

10.2.1.9

MAX_REG_APPS Macro

File

ARP.c

166

10.2 ARP Microchip TCP/IP Stack Help ARP Stack Members

#define

MAX_REG_APPS 2

// MAX num allowed registrations of Modules/Apps

Description

MAX num allowed registrations of Modules/Apps

10.2.2

ARP Stack Members

Functions

Name

ARPInit ( see page 167)

ARPProcess ( see page

167)

Module

SwapARPPacket ( see page 169)

Description

Initializes the ARP module.

Processes an incoming ARP packet.

Description

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.

10.2.2.1

ARPInit Function

File

ARP.h

C void

ARPInit();

Returns

None

Description

Initializes the ARP module. Call this function once at boot to invalidate the cached lookup.

Remarks

This function is only required when the stack is a client, and therefore is only enabled when STACK_CLIENT_MODE is enabled.

Preconditions

None

10.2.2.2

ARPProcess Function

File

ARP.h

BOOL ARPProcess();

167

10.2 ARP Microchip TCP/IP Stack Help ARP Internal Members

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

TRUE

FALSE

Description

All processing of this ARP packet is complete. Do not call again until a new

ARP packet is waiting in the RX buffer.

This function must be called again. More time is needed to send an ARP response.

10.2.3

ARP Internal Members

Functions

Name

ARPPut ( see page 169)

Description

Writes an ARP packet to the MAC.

Swaps endian-ness of header information in an ARP packet.

Macros

Module

ARP_OPERATION_REQ ( see page 170)

Variables

Name

Description

Operation code indicating an ARP Request

ARP_OPERATION_RESP ( see page 170)

Operation code indicating an ARP Response

HW_ETHERNET ( see page 170)

ARP Hardware type as defined by IEEE 802.3

ARP_IP ( see page 170)

ARP IP packet type as defined by IEEE 802.3

Name

Cache ( see page 170)

Description

Cache for one ARP response

reg_apps ( see page 171)

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 ( see page 171);

Description

The following functions and variables are designated as internal to the ARP module.

168

10.2 ARP Microchip TCP/IP Stack Help ARP Internal Members

10.2.3.1

ARPPut Function

File

ARP.c

C static

BOOL ARPPut(

ARP_PACKET* packet

);

Description

Writes an ARP packet to the MAC.

Preconditions

None

Parameters

packet

Description

A pointer to an ARP_PACKET ( see page 171) structure with correct

operation and target preconfigured.

Return Values

TRUE

FALSE

Section

Helper Function Prototypes

Description

The ARP packet was generated properly

Not a possible return value

10.2.3.2

SwapARPPacket Function

File

ARP.h

C void

SwapARPPacket(

ARP_PACKET* p

);

Returns

None

Description

Swaps endian-ness of header information in an ARP packet.

Preconditions

None

Parameters

Description

The ARP packet to be swapped

169

10.2 ARP Microchip TCP/IP Stack Help ARP Internal Members

10.2.3.3

ARP_OPERATION_REQ Macro

File

ARP.h

#define

ARP_OPERATION_REQ 0x0001u

// Operation code indicating an ARP Request

Description

Operation code indicating an ARP Request

10.2.3.4

ARP_OPERATION_RESP Macro

File

ARP.h

#define

ARP_OPERATION_RESP 0x0002u

// Operation code indicating an ARP Response

Description

Operation code indicating an ARP Response

10.2.3.5

HW_ETHERNET Macro

File

ARP.c

#define

HW_ETHERNET (0x0001u)

// ARP Hardware type as defined by IEEE 802.3

Description

ARP Hardware type as defined by IEEE 802.3

10.2.3.6

ARP_IP Macro

File

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

10.2.3.7

Cache Variable

File

ARP.c

170

10.2 ARP

NODE_INFO Cache;

Description

Cache for one ARP response

Microchip TCP/IP Stack Help Types

10.2.3.8

reg_apps Variable

File

ARP.c

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 ( see page 171);

10.2.4

Types

Module

The operation the sender is performing (ARP_REQ ( see page 166) or

Structures

Name

ARP_PACKET ( see page

171)

Description

ARP packet structure

10.2.4.1

ARP_PACKET Structure

File

ARP.h

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;

Members

WORD HardwareType;

WORD Protocol;

Description

Link-layer protocol type (Ethernet is 1).

The upper-layer protocol issuing an ARP request (0x0800 for IPv4)..

171

10.3 Berkeley (BSD) Sockets

BYTE MACAddrLen;

BYTE ProtocolLen;

WORD Operation;

MAC_ADDR SenderMACAddr;

IP_ADDR SenderIPAddr;

MAC_ADDR TargetMACAddr;

IP_ADDR TargetIPAddr;

Description

ARP packet structure

Microchip TCP/IP Stack Help BSD Wrapper Public Members

MAC address length (6).

Length of addresses used in the upper-layer protocol (4).

ARP_RESP ( see page 166)).

The sender's hardware (MAC) address.

The sender's IP address.

The target node's hardware (MAC) address.

The target node's IP address.

10.3

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.

172

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help BSD Wrapper Public Members

10.3.1

BSD Wrapper Public Members

Functions

Name

accept ( see page 174)

Description

This function accepts connection requests queued for a listening socket.

bind ( see page 175)

This function assigns a name to the socket descriptor.

closesocket ( see page 176) The closesocket function closes an existing socket.

connect ( see page 176)

gethostname ( see page

177)

listen ( see page 180) recv ( see page 180)

This function connects to the peer communications end point.

Returns the standard host name for the system.

recvfrom ( see page 181)

send ( see page 182)

The listen function sets the specified socket in a listen mode

The recv() function is used to receive incoming data that has been queued for a socket.

The recvfrom() function is used to receive incoming data that has been queued for a socket.

The send function is used to send outgoing data on an already connected socket.

sendto ( see page 182)

socket ( see page 185)

This function used to send the data for both connection oriented and connection-less sockets.

This function creates a new Berkeley socket.

Macros

Name

AF_INET ( see page 175)

Description

Internet Address ( see page 152) Family - UDP, TCP, etc.

INADDR_ANY ( see page 178)

IP address for server binding.

INVALID_TCP_PORT ( see page 179)

Invalide TCP port

IP_ADDR_ANY ( see page 179)

IP Address ( see page 152) for server binding

IPPROTO_IP ( see page 179)

Indicates IP pseudo-protocol.

IPPROTO_TCP ( see page 179) Indicates TCP for the internet address family.

IPPROTO_UDP ( see page 179) Indicates UDP for the internet address family.

SOCK_DGRAM ( see page 183) Connectionless datagram socket. Use UDP for the internet address family.

SOCK_STREAM ( see page

183)

Connection based byte streams. Use TCP for the internet address family.

SOCKET_CNXN_IN_PROGRESS

( see page 185)

Socket connection state.

SOCKET_DISCONNECTED ( see page 186)

Socket disconnected

SOCKET_ERROR ( see page

186)

Socket error

Module

Berkeley (BSD) Sockets ( see page 172)

173

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help

Structures

Name Description

BSDSocket ( see page 175) Berkeley Socket structure

in_addr ( see page 178)

in_addr structure

sockaddr ( see page 183)

generic address structure for all address families

sockaddr_in ( see page 184) In the Internet address family

Types

Name

SOCKADDR ( see page

184)

Description

generic address structure for all address families

SOCKADDR_IN ( see page

184)

In the Internet address family

SOCKET ( see page 185)

Socket descriptor

Description

The following functions and variables are available to the stack application.

BSD Wrapper Public Members

10.3.1.1

accept Function

File

BerkeleyAPI.h

SOCKET accept(

value INVALID_SOCKET ( see page 533) is returned.

struct

sockaddr* addr,

int

* addrlen

);

Returns

If the accept function succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. Otherwise, the

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 ( see page 183)

type socket.

Remarks

None.

Preconditions

listen ( see page 180) function should be called.

Parameters

s addr addrlen

Description

Socket descriptor returned from a previous call to socket. must be bound to a local name and in listening mode.

Optional pointer to a buffer that receives the address of the connecting entity.

Optional pointer to an integer that contains the length of the address addr

174

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help BSD Wrapper Public Members

10.3.1.2

AF_INET Macro

File

BerkeleyAPI.h

#define

AF_INET 2

// Internet Address Family - UDP, TCP, etc.

Description

Internet Address ( see page 152) Family - UDP, TCP, etc.

10.3.1.3

bind Function

File

BerkeleyAPI.h

C int

bind(

If bind is successful, a value of 0 is returned. A return value of SOCKET_ERROR ( see page 186) indicates an error.

const struct

sockaddr* name,

int

namelen

);

Returns

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 ( see page 183), the name of the remote endpoint is assigned when a

connect ( see page 176) or accept ( see page 174) function is executed.

Remarks

None.

Preconditions

socket function should be called.

Parameters

s name namelen

Description

Socket descriptor returned from a previous call to socket.

pointer to the sockaddr ( see page 183) structure containing the local address

of the socket.

length of the sockaddr ( see page 183) structure.

10.3.1.4

BSDSocket Structure

File

BerkeleyAPI.h

C struct

BSDSocket {

int

SocketType;

BSD_SCK_STATE bsdState;

WORD localPort;

175

10.3 Berkeley (BSD) Sockets

WORD remotePort;

DWORD remoteIP;

int

backlog;

BOOL isServer;

TCP_SOCKET SocketID;

};

Members

int SocketType;

BSD_SCK_STATE bsdState;

WORD localPort;

WORD remotePort;

DWORD remoteIP; int backlog;

BOOL isServer;

TCP_SOCKET SocketID;

Description

Berkeley Socket structure

Microchip TCP/IP Stack Help

Description

Socket type

Socket state local port remote port remote IP maximum number or client connection server/client check

Socket ID

BSD Wrapper Public Members

10.3.1.5

closesocket Function

File

BerkeleyAPI.h

C int

closesocket(

SOCKET s

);

Returns

If closesocket is successful, a value of 0 is returned. A return value of SOCKET_ERROR ( see page 186) (-1) indicates an

error.

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.

Remarks

None.

Preconditions

None.

Parameters

Description

Socket descriptor returned from a previous call to socket

10.3.1.6

connect Function

File

BerkeleyAPI.h

176

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help BSD Wrapper Public Members

C int

connect(

If the connect() function succeeds, it returns 0. Otherwise, the value SOCKET_ERROR ( see page 186) is returned to

struct

sockaddr* name,

int

namelen

);

Returns

indicate an error condition. For stream based socket, if the connection is not established yet, connect returns

SOCKET_CNXN_IN_PROGRESS ( see page 185).

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.

Remarks

None.

Preconditions

socket function should be called.

Parameters

s name namelen

Description

Socket descriptor returned from a previous call to socket.

pointer to the sockaddr ( see page 183) structure containing the peer address

and port number.

length of the sockaddr ( see page 183) structure.

10.3.1.7

gethostname Function

File

BerkeleyAPI.h

C int

gethostname(

char

* name,

int

namelen

);

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 ( see page 186) (-1) will be returned. On error, *name will be unmodified and no null terminator will be generated.

Description

This function returns the standard host name of the system which is calling this function. The returned name is null-terminated.

Remarks

None.

Preconditions

None.

177

10.3 Berkeley (BSD) Sockets

Parameters

name namelen

Microchip TCP/IP Stack Help BSD Wrapper Public Members

Description

Pointer to a buffer that receives the local host name.

size of the name array.

10.3.1.8

in_addr Structure

File

BerkeleyAPI.h

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;

};

Members

Description

union of IP address

Members

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; 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;

Description

in_addr structure

IP address in Byte

IP address in Word

IP address

10.3.1.9

INADDR_ANY Macro

File

BerkeleyAPI.h

#define

INADDR_ANY 0x00000000u

// IP address for server binding.

Description

IP address for server binding.

178

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help BSD Wrapper Public Members

10.3.1.10

INVALID_TCP_PORT Macro

File

BerkeleyAPI.h

#define

INVALID_TCP_PORT (0L)

//Invalide TCP port

Description

Invalide TCP port

10.3.1.11

IP_ADDR_ANY Macro

File

BerkeleyAPI.h

#define

IP_ADDR_ANY 0u

// IP Address for server binding

Description

IP Address ( see page 152) for server binding

10.3.1.12

IPPROTO_IP Macro

File

BerkeleyAPI.h

#define

IPPROTO_IP 0

// Indicates IP pseudo-protocol.

Description

Indicates IP pseudo-protocol.

10.3.1.13

IPPROTO_TCP Macro

File

BerkeleyAPI.h

#define

IPPROTO_TCP 6

// Indicates TCP for the internet address family.

Description

Indicates TCP for the internet address family.

10.3.1.14

IPPROTO_UDP Macro

File

BerkeleyAPI.h

179

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help BSD Wrapper Public Members

#define

IPPROTO_UDP 17

// Indicates UDP for the internet address family.

Description

Indicates UDP for the internet address family.

10.3.1.15

listen Function

File

BerkeleyAPI.h

C int

listen(

Returns 0 on success, else return SOCKET_ERROR ( see page 186).

int

backlog

);

Returns

Description

This function sets the specified socket in a listen mode. Calling the listen function indicates that the application is ready to

accept (

see page 174) connection requests arriving at a socket of type SOCK_STREAM ( see page 183). The

connection request is queued (if possible) until accepted with an accept ( see page 174) function. The backlog parameter

defines the maximum number of pending connections that may be queued.

Remarks

None

Preconditions

bind() must have been called on the s socket first.

Parameters

s backlog

Description

Socket identifier returned from a prior socket() call.

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

10.3.1.16

recv Function

File

BerkeleyAPI.h

C int

recv(

available. A return value of SOCKET_ERROR ( see page 186) (-1) indicates an error condition. A return value of

char

* buf,

int

len,

int

flags

);

Returns

If recv is successful, the number of bytes copied to application buffer buf is returned. A value of zero indicates no data

180

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help BSD Wrapper Public Members

SOCKET_DISCONNECTED ( see page 186) indicates the connection no longer exists.

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 ( see page 183) type sockets. For SOCK_STREAM ( see page 183) types, the data

is buffered internally so the application can retreive all data by multiple calls of recvfrom ( see page 181).

Remarks

None.

Preconditions

connect ( see page 176) function should be called for TCP and UDP sockets. Server side, accept ( see page 174)

function should be called.

Parameters

s buf len flags

Description

Socket descriptor returned from a previous call to socket.

application data receive buffer.

buffer length in bytes.

no significance in this implementation

10.3.1.17

recvfrom Function

File

BerkeleyAPI.h

C int

recvfrom(

available. A return value of SOCKET_ERROR ( see page 186) (-1) indicates an error condition.

char

* buf,

int

len,

int

flags,

struct

sockaddr* from,

int

* fromlen

);

Returns

If recvfrom is successful, the number of bytes copied to application buffer buf is returned. A value of zero indicates no data

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 ( see page 183) type sockets. For SOCK_STREAM ( see page 183)

types, the data is buffered internally so the application can retreive all data by multiple calls of recvfrom.

Remarks

None.

Preconditions

socket function should be called.

Parameters

Description

Socket descriptor returned from a previous call to socket.

181

10.3 Berkeley (BSD) Sockets buf len flags from fromlen

Microchip TCP/IP Stack Help BSD Wrapper Public Members application data receive buffer.

buffer length in bytes.

message flags. Currently this is not supported.

pointer to the sockaddr ( see page 183) structure that will be filled in with the

destination address.

size of buffer pointed by from.

10.3.1.18

send Function

File

BerkeleyAPI.h

C int

send(

On success, send returns number of bytes sent. In case of error, returns SOCKET_ERROR ( see page 186). a zero

const char

* buf,

int

len,

int

flags

);

Returns

indicates no data send.

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 ( see page 183) but can also be used to send datagrams on a socket of type SOCK_DGRAM ( see page 183).

Remarks

None.

Preconditions

connect ( see page 176) function should be called for TCP and UDP sockets. Server side, accept ( see page 174)

function should be called.

Parameters

s buf len flags

Description

Socket descriptor returned from a previous call to socket.

application data buffer containing data to transmit.

length of data in bytes.

message flags. Currently this field is not supported.

10.3.1.19

sendto Function

File

BerkeleyAPI.h

C int

sendto(

On success, sendto returns number of bytes sent. In case of error returns SOCKET_ERROR ( see page 186)

const char

* buf,

int

len,

int

flags,

const struct

sockaddr* to,

int

tolen

182

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help BSD Wrapper Public Members

);

Returns

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.

Remarks

None.

Preconditions

socket function should be called.

Parameters

s buf len flags to tolen

Description

Socket descriptor returned from a previous call to socket.

application data buffer containing data to transmit.

length of data in bytes.

message flags. Currently this field is not supported.

Optional pointer to the the sockaddr ( see page 183) structure containing the

destination address. If NULL, the currently bound remote port and IP address are used as the destination.

length of the sockaddr ( see page 183) structure.

10.3.1.20

SOCK_DGRAM Macro

File

BerkeleyAPI.h

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

10.3.1.21

SOCK_STREAM Macro

File

BerkeleyAPI.h

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

10.3.1.22

sockaddr Structure

File

BerkeleyAPI.h

183

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help

C struct

sockaddr {

unsigned short

sa_family;

char

sa_data[14];

};

Members

unsigned short sa_family; char sa_data[14];

Description

address family up to 14 bytes of direct address

Description

generic address structure for all address families

BSD Wrapper Public Members

10.3.1.23

SOCKADDR Type

File

BerkeleyAPI.h

C typedef struct

sockaddr SOCKADDR;

Description

generic address structure for all address families

10.3.1.24

sockaddr_in Structure

File

BerkeleyAPI.h

C struct

sockaddr_in {

short

sin_family;

WORD sin_port;

struct

in_addr sin_addr;

char

sin_zero[8];

};

Members

short sin_family;

WORD sin_port; struct in_addr sin_addr; char sin_zero[8];

Description

In the Internet address family

Description

Address ( see page 152) family; must be AF_INET ( see page 175).

Internet Protocol (IP) port.

IP address in network byte order.

Padding to make structure the same size as SOCKADDR ( see page 184).

10.3.1.25

SOCKADDR_IN Type

File

BerkeleyAPI.h

184

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help

C typedef struct

sockaddr_in SOCKADDR_IN;

Description

In the Internet address family

BSD Wrapper Public Members

10.3.1.26

socket Function

File

BerkeleyAPI.h

SOCKET socket(

int

af,

int

type,

int

protocol

);

Returns

New socket descriptor. INVALID_SOCKET ( see page 533) in case of error.

Description

This function creates a new BSD socket for the microchip TCPIP stack. The return socket descriptor is used for the subsequent BSD operations.

Remarks

None.

Preconditions

BerkeleySocketInit ( see page 186) function should be called.

Parameters

af type protocol

Description

address family - AF_INET ( see page 175).

socket type SOCK_DGRAM ( see page 183) or SOCK_STREAM ( see page

183).

IP protocol IPPROTO_UDP ( see page 179) or IPPROTO_TCP ( see page

179).

10.3.1.27

SOCKET Type

File

BerkeleyAPI.h

C typedef

BYTE SOCKET;

Description

Socket descriptor

10.3.1.28

SOCKET_CNXN_IN_PROGRESS Macro

File

BerkeleyAPI.h

185

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help

#define

SOCKET_CNXN_IN_PROGRESS (-2)

//Socket connection state.

Description

Socket connection state.

10.3.1.29

SOCKET_DISCONNECTED Macro

File

BerkeleyAPI.h

#define

SOCKET_DISCONNECTED (-3)

//Socket disconnected

Description

Socket disconnected

10.3.1.30

SOCKET_ERROR Macro

File

BerkeleyAPI.h

#define

SOCKET_ERROR (-1)

//Socket error

Description

Socket error

BSD Wrapper Stack Members

10.3.2

BSD Wrapper Stack Members

Functions

Name

BerkeleySocketInit ( see page 186)

Module

Berkeley (BSD) Sockets ( see page 172)

Description

Initializes the Berkeley socket structure array.

Description

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.

10.3.2.1

BerkeleySocketInit Function

File

BerkeleyAPI.h

C void

BerkeleySocketInit();

186

10.3 Berkeley (BSD) Sockets Microchip TCP/IP Stack Help BSD Wrapper Internal Members

Returns

None

Description

This function initializes the Berkeley socket array. This function should be called before any BSD socket call.

Remarks

None.

Preconditions

None.

10.3.3

BSD Wrapper Internal Members

Enumerations

Name

BSD_SCK_STATE ( see page 187)

Description

Berkeley Socket (BSD) states

Functions

Name Description

HandlePossibleTCPDisconnection

( see page 188)

Internal function that checks for asynchronous TCP connection state changes and resynchs the BSD socket descriptor state to match.

Module

Berkeley (BSD) Sockets ( see page 172)

Variables

Name

BSDSocketArray ( see page 188) gAutoPortNumber ( see page 188)

Description

Array of BSDSocket ( see page 175) elements; used to track all socket state

and connection information.

Contains the next local port number to associate with a socket.

Description

The following functions and variables are designated as internal to the module.

10.3.3.1

BSD_SCK_STATE Enumeration

File

BerkeleyAPI.h

C typedef enum

{

SKT_CLOSED,

SKT_CREATED,

SKT_BOUND,

SKT_BSD_LISTEN,

SKT_LISTEN,

SKT_IN_PROGRESS,

SKT_EST,

SKT_DISCONNECTED

} BSD_SCK_STATE;

187

10.3 Berkeley (BSD) Sockets

Members

SKT_CLOSED

SKT_CREATED

SKT_BOUND

SKT_BSD_LISTEN

SKT_LISTEN

SKT_IN_PROGRESS

SKT_EST

SKT_DISCONNECTED

Description

Berkeley Socket (BSD) states

Microchip TCP/IP Stack Help BSD Wrapper Internal Members

Description

Socket closed state indicating a free descriptor

Socket created state for TCP and UDP sockets

Socket bound state for TCP and UDP sockets

Listening state for TCP BSD listener handle "socket

TCP server listen ( see page 180) state

TCP client connection in progress state

TCP client or server established state

TCP client or server no longer connected to the remote host (but was historically)

10.3.3.2

BSDSocketArray Variable

File

BerkeleyAPI.c

C struct

BSDSocket BSDSocketArray[BSD_SOCKET_COUNT];

Description

Array of BSDSocket ( see page 175) elements; used to track all socket state and connection information.

10.3.3.3

gAutoPortNumber Variable

File

BerkeleyAPI.c

WORD gAutoPortNumber = 1024;

Description

Contains the next local port number to associate with a socket.

10.3.3.4

HandlePossibleTCPDisconnection Function

File

BerkeleyAPI.c

C static

BOOL HandlePossibleTCPDisconnection(

SOCKET s

);

Returns

TRUE - Socket is disconnected FALSE - Socket is

Description

Internal function that checks for asynchronous TCP connection state changes and resynchs the BSD socket descriptor state

188

Microchip TCP/IP Stack Help DNS Public Members 10.4 DNS Client to match.

Preconditions

None

Parameters

Description

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.

10.4

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 ( see page 547) 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.

10.4.1

DNS Public Members

Functions

Name

DNSBeginUsage ( see page 190)

DNSEndUsage ( see page

190)

DNSResolve ( see page

191)

DNSResolveROM ( see page 191)

DNSIsResolved ( see page

192)

Description

Claims access to the DNS module.

Releases control of the DNS module.

Begins resolution of an address.

Determines if the DNS resolution is complete and provides the IP.

Macros

Name

DNS_TYPE_A ( see page

192)

Description

Constant for record type in DNSResolve ( see page 191). Indicates an A

(standard address) record.

189

10.4 DNS Client Microchip TCP/IP Stack Help DNS Public Members

DNS_TYPE_MX ( see page

193)

Constant for record type in DNSResolve ( see page 191). Indicates an MX

(mail exchanger) record.

Module

DNS Client ( see page 189)

Description

The following functions and variables are available to the stack application.

10.4.1.1

DNSBeginUsage Function

File

DNS.h

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 ( see page 190) when this application no longer needs the DNS

module so that other applications may make use of it.

Remarks

Ensure that DNSEndUsage ( see page 190) 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.

Preconditions

Stack is initialized.

Return Values

TRUE

FALSE

Description

No other DNS resolutions are in progress and the calling application has sucessfully taken ownership of the DNS module

The DNS module is currently in use. Yield to the stack and attempt this call again later.

10.4.1.2

DNSEndUsage Function

File

DNS.h

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.

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.

Preconditions

DNSBeginUsage ( see page 190) returned TRUE on a previous call.

190

10.4 DNS Client

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help

Description

The address to the host name was successfully resolved.

The DNS failed or the address does not exist.

DNS Public Members

10.4.1.3

DNSResolve Function

File

DNS.h

C void

DNSResolve(

BYTE* HostName,

BYTE Type

);

Returns

None

Description

This function attempts to resolve a host name to an IP address. When called, it starts the DNS state machine. Call

DNSIsResolved ( see page 192) 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.

Remarks

This function requires access to one UDP socket. If none are available, MAX_UDP_SOCKETS may need to be increased.

Preconditions

DNSBeginUsage ( see page 190) returned TRUE on a previous call.

Parameters

Hostname

RecordType ( see page 196)

Description

A pointer to the null terminated string specifiying the host for which to resolve an IP.

DNS_TYPE_A ( see page 192) or DNS_TYPE_MX ( see page 193)

depending on what type of record resolution is desired.

10.4.1.4

DNSResolveROM Function

File

DNS.h

C void

DNSResolveROM(

ROM BYTE* Hostname,

BYTE Type

);

Returns

None

Description

This function attempts to resolve a host name to an IP address. When called, it starts the DNS state machine. Call

DNSIsResolved ( see page 192) repeatedly to determine if the resolution is complete.

191

10.4 DNS Client Microchip TCP/IP Stack Help DNS Public Members

Only one DNS resoultion may be executed at a time. The Hostname must not be modified in memory until the resolution is complete.

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 ( see page 191) on non-PIC18 platforms.

Preconditions

DNSBeginUsage ( see page 190) returned TRUE on a previous call.

Parameters

Hostname

RecordType ( see page 196)

Description

A pointer to the null terminated string specifiying the host for which to resolve an IP.

DNS_TYPE_A ( see page 192) or DNS_TYPE_MX ( see page 193)

depending on what type of record resolution is desired.

10.4.1.5

DNSIsResolved Function

File

DNS.h

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 ( see page 191) or DNSResolveROM ( see page 191) has been called.

Parameters

HostIP

Description

A pointer to an IP_ADDR structure in which to store the resolved IP address once resolution is complete.

Return Values

TRUE

FALSE

Description

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.

The resolution process is still in progress.

10.4.1.6

DNS_TYPE_A Macro

File

DNS.h

#define

DNS_TYPE_A (1u)

// Constant for record type in DNSResolve. Indicates an A

(standard address) record.

192

10.4 DNS Client Microchip TCP/IP Stack Help

Description

Constant for record type in DNSResolve ( see page 191). Indicates an A (standard address) record.

DNS Internal Members

10.4.1.7

DNS_TYPE_MX Macro

File

DNS.h

#define

DNS_TYPE_MX (15u)

// Constant for record type in DNSResolve. Indicates an

MX (mail exchanger) record.

Description

Constant for record type in DNSResolve ( see page 191). Indicates an MX (mail exchanger) record.

10.4.2

DNS Internal Members

Functions

Name

DNSPutString ( see page

194)

DNSPutROMString ( see page 194)

DNSDiscardName ( see page 197)

Description

Writes a string to the DNS socket.

Writes a ROM string to the DNS socket.

Reads a name string or string pointer from the DNS socket and discards it.

Macros

Name

DNS_PORT ( see page

195)

DNS_TIMEOUT ( see page

195)

Description

Default port for DNS resolutions

Elapsed time after which a DNS resolution is considered to have timed out

Module

DNS Client ( see page 189)

Structures

Name

DNS_HEADER ( see page

197)

Description

Structure for the DNS header

Variables

Name

DNSHostName ( see page

195)

DNSHostNameROM ( see page 195)

Flags ( see page 196)

RecordType ( see page

196)

Description

Host name in RAM to look up

Host name in ROM to look up

Stores various flags for the UDP module

Record type being queried

193

10.4 DNS Client Microchip TCP/IP Stack Help

ResolvedInfo ( see page

196) smDNS ( see page 196)

Node information about the resolved node

State machine for a DNS query

Description

The following functions and variables are designated as internal to the DNS module.

10.4.2.1

DNSPutString Function

File

DNS.c

C static void

DNSPutString(

BYTE* String

);

Returns

None

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

String

Section

Function Prototypes

Description

the string to write to the UDP socket.

10.4.2.2

DNSPutROMString Function

File

DNS.c

C static void

DNSPutROMString(

ROM BYTE* String

);

Returns

None

Description

This function writes a string to the DNS socket, ensuring that it is properly formatted.

Remarks

This function is aliased to DNSPutString ( see page 194) on non-PIC18 platforms.

Preconditions

UDP socket is obtained and ready for writing.

DNS Internal Members

194

10.4 DNS Client

Parameters

String

Microchip TCP/IP Stack Help

Description

the string to write to the UDP socket.

10.4.2.3

DNS_PORT Macro

File

DNS.c

#define

DNS_PORT 53u

// Default port for DNS resolutions

Description

Default port for DNS resolutions

DNS Internal Members

10.4.2.4

DNS_TIMEOUT Macro

File

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

10.4.2.5

DNSHostName Variable

File

DNS.c

BYTE * DNSHostName;

Description

Host name in RAM to look up

10.4.2.6

DNSHostNameROM Variable

File

DNS.c

ROM BYTE * DNSHostNameROM;

Description

Host name in ROM to look up

195

10.4 DNS Client Microchip TCP/IP Stack Help

10.4.2.7

Flags Variable

File

UDP.c

C struct

{

unsigned char

bFirstRead : 1;

unsigned char

bWasDiscarded : 1;

} Flags;

Members

unsigned char bFirstRead : 1; unsigned char bWasDiscarded : 1;

Description

Stores various flags for the UDP module

Description

No data has been read from this segment yet

The data in this segment has been discarded

10.4.2.8

RecordType Variable

File

DNS.c

BYTE RecordType;

Description

Record type being queried

10.4.2.9

ResolvedInfo Variable

File

DNS.c

NODE_INFO ResolvedInfo;

Description

Node information about the resolved node

10.4.2.10

smDNS Variable

File

DNS.c

C enum

{

DNS_START = 0,

DNS_ARP_START_RESOLVE,

DNS_ARP_RESOLVE,

DNS_OPEN_SOCKET,

DNS_QUERY,

DNS Internal Members

196

10.5 Dynamic DNS Client

DNS_GET_RESULT,

DNS_FAIL,

DNS_DONE

} smDNS;

Members

DNS_START = 0

DNS_ARP_START_RESOLVE

DNS_ARP_RESOLVE

DNS_OPEN_SOCKET

DNS_QUERY

DNS_GET_RESULT

DNS_FAIL

DNS_DONE

Description

State machine for a DNS query

Microchip TCP/IP Stack Help

Description

Initial state to reset client state variables

Send ARP resolution of DNS server or gateway MAC address

Wait for response to ARP request

Open UDP socket

Send DNS query to DNS server

Wait for response from DNS server

ARP or DNS server not responding

DNS query is finished

10.4.2.11

DNS_HEADER Structure

File

DNS.c

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

10.4.2.12

DNSDiscardName Function

File

DNS.c

C static void

DNSDiscardName();

Returns

None

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

197

10.5 Dynamic DNS Client Microchip TCP/IP Stack Help Dynamic DNS Public Members

10.5

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 DynDNS.org

, No-IP.com

, and DNS-O-Matic.com

IMPORTANT: The dynamic DNS services stipulate that updates should be made no more frequently than 10 minutes, and only when the IP address has changed. Updates made more often than that are considered abusive, and may eventually cause your account to be disabled. Production devices that get rebooted frequently may need to store the last known IP in non-volatile memory. You also should not enable this module while testing the rest of your application.

10.5.1

Dynamic DNS Public Members

Enumerations

Name

DDNS_SERVICES ( see page 200)

Description

Dynamic DNS Services. Must support the DynDNS ( see page 198) API

(Auxlang) and correspond to ddnsServiceHosts ( see page 205) and ddnsServicePorts ( see page 205) in DynDNS.c.

DDNS_STATUS ( see page

200)

Status message for DynDNS ( see page 198) client. GOOD and NOCHG are

ok, but ABUSE through 911 are fatal. UNCHANGED through INVALID are locally defined.

Functions

Name

DDNSForceUpdate ( see page 201)

DDNSGetLastIP ( see page

202)

Description

Forces an immediate DDNS update

Returns the last known external IP address of the device.

DDNSGetLastStatus ( see page 202)

DDNSSetService ( see page 202)

Returns the status of the most recent update.

Selects a pre-configured Dynamic DNS service

Module

DDNS_POINTERS ( see page 199)

Structures

Name

Variables

Description

Configuration parameters for the Dynamic DNS Client

Name Description

DDNSClient ( see page 201) Configuration parameters for the module

198

10.5 Dynamic DNS Client Microchip TCP/IP Stack Help

Description

These functions and variables are meant to be called by your stack application.

Dynamic DNS Public Members

10.5.1.1

DDNS_POINTERS Structure

File

DynDNS.h

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 ( see page 201).[field name].szRAM

to use a string stored in RAM, or

DDNSClient ( see page 201).[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

CheckIPServer

CheckIPPort

UpdateServer

UpdatePort

Username

Password

Host

ROMPointers

Description

The server used to determine the external IP address

Port on the above server to connect ( see page 176) to

The server where updates should be posted

Port on the above server to connect ( see page 176) to

The user name for the dynamic DNS server

The password to supply when making updates

The host name you wish to update

Indicates which parameters to read from ROM instead of RAM.

199

10.5 Dynamic DNS Client Microchip TCP/IP Stack Help Dynamic DNS Public Members

10.5.1.2

DDNS_SERVICES Enumeration

File

DynDNS.h

C typedef enum

{

DYNDNS_ORG = 0u,

NO_IP_COM,

DNSOMATIC_COM

} DDNS_SERVICES;

Members

DYNDNS_ORG = 0u

NO_IP_COM

DNSOMATIC_COM

Description

www.dyndns.org

www.no-ip.com

www.dnsomatic.com

Description

Dynamic DNS Services. Must support the DynDNS ( see page 198) API (Auxlang) and correspond to ddnsServiceHosts ( see page 205) and ddnsServicePorts ( see page 205) in DynDNS.c.

10.5.1.3

DDNS_STATUS Enumeration

File

DynDNS.h

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;

Members

DDNS_STATUS_GOOD = 0u

DDNS_STATUS_NOCHG

DDNS_STATUS_ABUSE

DDNS_STATUS_BADSYS

DDNS_STATUS_BADAGENT

Description

Update successful, hostname is now updated

Update changed no setting and is considered abusive. Additional 'nochg' updates will cause hostname to be blocked.

The hostname specified is blocked for update abuse.

System parameter not valid. Should be dyndns, statdns or custom.

The user agent was blocked or not sent.

200

10.5 Dynamic DNS Client Microchip TCP/IP Stack Help Dynamic DNS Public Members

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

The username and password pair do not match a real user.

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.

The hostname specified is not a fully-qualified domain name (not in the form hostname.dyndns.org or domain.com).

The hostname specified does not exist in this user account (or is not in the service specified in the system parameter).

The hostname specified does not belong to this user account.

Too many hosts specified in an update.

Unspecified DNS error encountered by the DDNS service.

There is a problem or scheduled maintenance with the DDNS service.

Error communicating with Update service.

The IP Check indicated that no update was necessary.

Error communicating with CheckIP service.

DDNS Client data is not valid.

DDNS client has not yet been executed with this configuration.

Description

Status message for DynDNS ( see page 198) client. GOOD and NOCHG are ok, but ABUSE through 911 are fatal.

UNCHANGED through INVALID are locally defined.

10.5.1.4

DDNSClient Variable

File

DynDNS.c

DDNS_POINTERS DDNSClient;

Description

Configuration parameters for the module

10.5.1.5

DDNSForceUpdate Function

File

DynDNS.h

C void

DDNSForceUpdate();

Returns

None

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 ( see page 201)

parameters have been modified.

Preconditions

DDNSInit ( see page 203) must have been called.

201

10.5 Dynamic DNS Client Microchip TCP/IP Stack Help Dynamic DNS Public Members

10.5.1.6

DDNSGetLastIP Function

File

DynDNS.h

IP_ADDR DDNSGetLastIP();

Returns

The last known external IP address of the device.

Description

This function returns the last known external IP address of the device.

Preconditions

None

10.5.1.7

DDNSGetLastStatus Function

File

DynDNS.h

DDNS_STATUS DDNSGetLastStatus();

Returns

DDNS_STATUS ( see page 200) indicating the status code for the most recent update.

Description

This function returns the status of the most recent update. See the DDNS_STATUS ( see page 200) enumeration for

possible codes.

Preconditions

None

10.5.1.8

DDNSSetService Function

File

DynDNS.h

C void

DDNSSetService(

DDNS_SERVICES svc

);

Returns

None

Description

This function selects a Dynamic DNS service based on parameters configured in ddnsServiceHosts ( see page 205) and

ddnsServicePorts ( see page 205). These arrays must match the DDNS_SERVICES ( see page 200) enumeration.

Preconditions

None

202

10.5 Dynamic DNS Client

Parameters

svc

Microchip TCP/IP Stack Help Dynamic DNS Stack Members

Description

one of the DDNS_SERVICES ( see page 200) elements to indicate the

selected service

10.5.2

Dynamic DNS Stack Members

Functions

Name Description

DDNSInit ( see page 203)

Initializes the Dynamic DNS module.

DDNSTask ( see page 203) Dynamic DNS client task/state machine.

Module

This function initializes the Dynamic DNS client. It clears the DDNSClient ( see page 201) pointers structure, and tells the

Description

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.

10.5.2.1

DDNSInit Function

File

DynDNS.h

C void

DDNSInit();

Returns

None

Description

module to attempt the first update after 15 seconds have elapsed (so as to allow the DHCP configuration to stabalize).

Remarks

This function is called only one during lifetime of the application.

Preconditions

None

10.5.2.2

DDNSTask Function

File

DynDNS.h

C void

DDNSTask();

Returns

None

203

10.5 Dynamic DNS Client Microchip TCP/IP Stack Help Dynamic DNS Internal Members

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 ( see page 205) elapses, which by default is every 10 minutes, or when an update is forced.

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.

Preconditions

DDNSInit ( see page 203)() has been called.

Section

Function Prototypes

10.5.3

Dynamic DNS Internal Members

Macros

Name

DDNS_CHECKIP_SERVER

( see page 206)

DDNS_DEFAULT_PORT ( see page 207)

Description

Default CheckIP server for determining current IP address

Default port for CheckIP server

Module

205) ddnsServiceHosts ( see page 205) ddnsServicePorts ( see page 205) dwUpdateAt ( see page

Variables

Name

bForceUpdate ( see page

205) lastKnownIP ( see page

205)

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.

Host names for various Dynamic DNS services

Port numbers for various Dynamic DNS services

Indicates when the next CheckIP should be done

Last known IP address of this device

lastStatus ( see page 206)

Status response from last update

_checkIpSrvrResponse ( see page 206)

Delimiter to locate IP address from CheckIP server

_updateIpSrvrResponse ( see page 206)

Response codes from DynDNS ( see page 198) Update Server

Description

The following functions and variables are designated as internal to the Dynamic DNS module.

204

10.5 Dynamic DNS Client Microchip TCP/IP Stack Help Dynamic DNS Internal Members

10.5.3.1

bForceUpdate Variable

File

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

10.5.3.2

ddnsServiceHosts Variable

File

CustomHTTPApp.c

ROM

char

* ROM ddnsServiceHosts[];

Description

Host names for various Dynamic DNS services

10.5.3.3

ddnsServicePorts Variable

File

DynDNS.c

ROM WORD ddnsServicePorts[] = { 80, 80, 80, };

Description

Port numbers for various Dynamic DNS services

10.5.3.4

dwUpdateAt Variable

File

DynDNS.c

DWORD dwUpdateAt;

Description

Indicates when the next CheckIP should be done

10.5.3.5

lastKnownIP Variable

File

DynDNS.c

205

10.5 Dynamic DNS Client

IP_ADDR lastKnownIP;

Description

Last known IP address of this device

Microchip TCP/IP Stack Help

10.5.3.6

lastStatus Variable

File

DynDNS.c

DDNS_STATUS lastStatus;

Description

Status response from last update

10.5.3.7

_checkIpSrvrResponse Variable

File

DynDNS.c

ROM BYTE _checkIpSrvrResponse[] = "Address:";

Description

Delimiter to locate IP address from CheckIP server

Dynamic DNS Internal Members

10.5.3.8

_updateIpSrvrResponse Variable

File

DynDNS.c

ROM

char

* _updateIpSrvrResponse[] = { "good", "nochg", "abuse", "badsys", "badagent",

"badauth", "!donator", "notfqdn", "nohost", "!yours", "numhost", "dnserr", "911", };

Description

Response codes from DynDNS ( see page 198) Update Server

10.5.3.9

DDNS_CHECKIP_SERVER Macro

File

DynDNS.h

#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

206

10.6 Hashes Microchip TCP/IP Stack Help Hashes Public Members

10.5.3.10

DDNS_DEFAULT_PORT Macro

File

DynDNS.h

#define

DDNS_DEFAULT_PORT (80u)

// Default port for CheckIP server

Description

Default port for CheckIP server

10.6

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 ( see page 211) structure and pass a pointer to it to either

MD5Initialize ( see page 210) or SHA1Initialize (

see page 210). Then, call HashAddData ( see page 208) or

HashAddROMData ( see page 208) as many times as are necessary to provide all the data to the hash. Call MD5Calculate

( see page 209) or SHA1Calculate ( see page 210) 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.

10.6.1

Hashes Public Members

Functions

Name

HashAddData ( see page

208)

HashAddROMData ( see page 208)

Description

Adds data to the hash sum.

207

10.6 Hashes Microchip TCP/IP Stack Help

MD5Calculate ( see page

209)

MD5Initialize ( see page

210)

SHA1Calculate ( see page

210)

SHA1Initialize ( see page

210)

Calculates an MD5 hash

Initializes a new MD5 hash.

Calculates a SHA-1 hash

Initializes a new SHA-1 hash.

Module

Structures

Name

HASH_SUM ( see page

211)

Description

Context storage for a hash operation

Description

The following functions and variables are available to the stack application.

10.6.1.1

HashAddData Function

File

Hashes.h

C void

HashAddData(

BYTE* data,

WORD len

);

Returns

None

Description

Adds data to the hash sum.

Remarks

This function calls the appropriate hashing function based on the hash typed defined in theSum.

Preconditions

The hash sum has already been initialized

Parameters

theSum data len

Description

hash context state the data to be added to the hash sum length of data

10.6.1.2

HashAddROMData Function

File

Hashes.h

Hashes Public Members

208

10.6 Hashes Microchip TCP/IP Stack Help

C void

HashAddROMData(

This function is aliased to HashAddData ( see page 208) on non-PIC18 platforms.

ROM BYTE* data,

WORD len

);

Returns

None

Description

Adds data to the hash sum.

Remarks

This function calls the appropriate hashing function based on the hash typed defined in theSum.

Preconditions

The hash sum has already been initialized

Parameters

theSum data len

Description

hash context state the data to be added to the hash sum length of data

Hashes Public Members

10.6.1.3

MD5Calculate Function

File

Hashes.h

C void

MD5Calculate(

pointer to the allocated HASH_SUM ( see page 211) object to initialize as MD5

BYTE* result

);

Returns

None

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

theSum result

Description

the current hash context

16 byte array in which to store the resulting hash

209

10.6 Hashes Microchip TCP/IP Stack Help Hashes Public Members

10.6.1.4

MD5Initialize Function

File

Hashes.h

C void

MD5Initialize(

HASH_SUM* theSum

);

Returns

None

Description

Initializes a new MD5 hash.

Preconditions

None

Parameters

theSum

Description

10.6.1.5

SHA1Calculate Function

File

Hashes.h

C void

SHA1Calculate(

pointer to the allocated HASH_SUM ( see page 211) object to initialize as

BYTE* result

);

Returns

None

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

theSum result

Description

the current hash context

20 byte array in which to store the resulting hash

10.6.1.6

SHA1Initialize Function

File

Hashes.h

210

10.6 Hashes

C void

SHA1Initialize(

HASH_SUM* theSum

);

Returns

None

Description

Initializes a new SHA-1 hash.

Preconditions

None

Parameters

theSum

Section

Function Prototypes

Microchip TCP/IP Stack Help Hashes Stack Members

Description

SHA-1

10.6.1.7

HASH_SUM Structure

File

Hashes.h

C typedef struct

{

DWORD h0;

DWORD h1;

DWORD h2;

DWORD h3;

DWORD h4;

DWORD bytesSoFar;

BYTE partialBlock[64];

HASH_TYPE hashType;

} HASH_SUM;

Members

DWORD h0;

DWORD h1;

DWORD h2;

DWORD h3;

DWORD h4;

DWORD bytesSoFar;

BYTE partialBlock[64];

HASH_TYPE hashType;

Description

Context storage for a hash operation

Description

Hash state h0

Hash state h1

Hash state h2

Hash state h3

Hash state h4

Total number of bytes hashed so far

Beginning of next 64 byte block

Type of hash being calculated

211

10.6 Hashes Microchip TCP/IP Stack Help Hashes Stack Members

10.6.2

Hashes Stack Members

Functions

Name

MD5AddROMData ( see page 212)

SHA1AddROMData ( see page 213)

SHA1AddData ( see page

213)

MD5AddData ( see page

214)

Module

Description

Adds data to an MD5 hash calculation.

Adds data to a SHA-1 hash calculation.

Adds data to an MD5 hash calculation.

Description

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.

10.6.2.1

MD5AddROMData Function

File

Hashes.h

C void

MD5AddROMData(

This function is aliased to MD5AddData ( see page 214) on non-PIC18 platforms.

ROM BYTE* data,

WORD len

);

Returns

None

Description

Adds data to an MD5 hash calculation.

Remarks

Preconditions

The hash context has already been initialized.

Parameters

theSum data len

Description

a pointer to the hash context structure the data to add to the hash the length of the data to add

212

10.6 Hashes Microchip TCP/IP Stack Help

10.6.2.2

SHA1AddROMData Function

File

Hashes.h

C void

SHA1AddROMData(

This function is aliased to SHA1AddData ( see page 213) on non-PIC18 platforms.

ROM BYTE* data,

WORD len

);

Returns

None

Description

Adds data to a SHA-1 hash calculation.

Remarks

Preconditions

The hash context has already been initialized.

Parameters

theSum data len

Description

a pointer to the hash context structure the data to add to the hash the length of the data to add

10.6.2.3

SHA1AddData Function

File

Hashes.h

C void

SHA1AddData(

BYTE* data,

WORD len

);

Returns

None

Description

Adds data to a SHA-1 hash calculation.

Preconditions

The hash context has already been initialized.

Parameters

theSum data

Description

a pointer to the hash context structure the data to add to the hash

Hashes Stack Members

213

10.6 Hashes len

Microchip TCP/IP Stack Help the length of the data to add

10.6.2.4

MD5AddData Function

File

Hashes.h

C void

MD5AddData(

BYTE* data,

WORD len

);

Returns

None

Description

Adds data to an MD5 hash calculation.

Preconditions

The hash context has already been initialized.

Parameters

theSum data len

Description

a pointer to the hash context structure the data to add to the hash the length of the data to add

10.6.3

Hashes Internal Members

Enumerations

Name

HASH_TYPE ( see page

215)

Description

Type of hash being calculated

Functions

Name Description

SHA1HashBlock ( see page

216)

Calculates the SHA-1 hash sum of a block.

MD5HashBlock ( see page

216)

Calculates the MD5 hash sum of a block.

Module

_MD5_r ( see page 215) lastBlock ( see page 215)

Variables

Name

_MD5_k ( see page 215)

Description

Array of pre-defined K values for MD5

Array of pre-defined R vales for MD5

Stores a copy of the last block with the required padding

Hashes Internal Members

214

10.6 Hashes Microchip TCP/IP Stack Help Hashes Internal Members

Description

The following functions and variables are designated as internal to the Hashes ( see page 207) module.

10.6.3.1

_MD5_k Variable

File

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

10.6.3.2

_MD5_r Variable

File

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

10.6.3.3

lastBlock Variable

File

Hashes.c

BYTE lastBlock[64];

Description

Stores a copy of the last block with the required padding

10.6.3.4

HASH_TYPE Enumeration

File

Hashes.h

215

10.6 Hashes

C typedef enum

{

HASH_MD5 = 0u,

HASH_SHA1

} HASH_TYPE;

Members

HASH_MD5 = 0u

HASH_SHA1

Description

Type of hash being calculated

Microchip TCP/IP Stack Help

Description

MD5 is being calculated

SHA-1 is being calculated

Hashes Internal Members

10.6.3.5

SHA1HashBlock Function

File

Hashes.c

C static void

SHA1HashBlock(

BYTE* data,

DWORD* h0,

DWORD* h1,

DWORD* h2,

DWORD* h3,

DWORD* h4

);

Returns

None

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

h2 h3 h4

Parameters

data h0 h1

Section

Functions and variables required for SHA-1

Description

The block of 64 bytes to hash the current hash context h0 value the current hash context h1 value the current hash context h2 value the current hash context h3 value the current hash context h4 value

10.6.3.6

MD5HashBlock Function

File

Hashes.c

216

10.7 Helpers Microchip TCP/IP Stack Help Helpers Public Members

C static void

MD5HashBlock(

BYTE* data,

DWORD* h0,

DWORD* h1,

DWORD* h2,

DWORD* h3

);

Returns

None

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

data h0 h1 h2 h3

Description

The block of 64 bytes to hash the current hash context h0 value the current hash context h1 value the current hash context h2 value the current hash context h3 value

10.7

Helpers

Functions

Name Description

LFSRRand ( see page 233) Returns a pseudo-random 16-bit unsigned integer in the range from 0 to 65535

(0x0000 to 0xFFFF).

LFSRSeedRand ( see page

233)

Seeds the LFSR random number generator invoked by the LFSRRand ( see page 233)() function. The prior seed is returned.

strncpy_m ( see page 234)

Copies multiple strings to a destination

Variables

Name

dwLFSRRandSeed ( see page 235)

Description

Default Random Number Generator seed. 0x41FE9F9E corresponds to calling

LFSRSeedRand ( see page 233)(1)

Description

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.

217

10.7 Helpers Microchip TCP/IP Stack Help Helpers Public Members

10.7.1

Helpers Public Members

Functions

Name

Base64Decode ( see page

219)

Base64Encode ( see page

219)

btohexa_high ( see page

220) btohexa_low ( see page

220)

Description

Decodes a Base-64 array to its literal representation.

Encodes a binary array to Base-64.

Converts the upper nibble of a binary value to a hexadecimal ASCII byte.

Converts the lower nibble of a binary value to a hexadecimal ASCII byte.

CalcIPChecksum ( see page 221)

ExtractURLFields ( see page 221)

Calculates an IP checksum value.

Extracts all parameters from an URL string (ex:

"http://admin:[email protected]:8080/myfile.gif" is split into

{PROTOCOL_HTTP, "admin", "passwd", "www.microchip.com", 8080,

"/myfile.gif"}.

Formats a string to a valid NetBIOS name.

FormatNetBIOSName ( see page 224)

GenerateRandomDWORD

( see page 225)

Generates a random DWORD.

Converts a hex string to a single byte.

Left-rotates a DWORD.

hexatob ( see page 225)

leftRotateDWORD ( see page 226)

Replace ( see page 226)

ROMStringToIPAddress ( see page 227)

stricmppgm2ram ( see page 228)

Replaces all instances of a particular substring with a new string

Converts a string to an IP address

Case-insensitive comparison of a string in RAM to a string in ROM.

StringToIPAddress ( see page 229) strupr ( see page 229)

strnchr ( see page 230)

Converts a string to an IP address

swapl ( see page 230)

swaps ( see page 231) uitoa ( see page 231)

ultoa ( see page 232)

UnencodeURL ( see page

232)

Converts a string to uppercase.

Searches a string up to a specified number of characters for a specific character.

Swaps the endian-ness of a DWORD.

Swaps the endian-ness of a WORD.

Converts an unsigned integer to a decimal string.

Decodes a URL-encoded string.

Macros

Name

leftRotateDWORD ( see page 226)

ROMStringToIPAddress ( see page 228)

Module

Converts the lower nibble of a binary value to a hexadecimal ASCII byte. For example, btohexa_high ( see page

Description

Rotations are more efficient in C30 and C32

Non-ROM variant for C30 and C32

218

10.7 Helpers Microchip TCP/IP Stack Help

Description

The following functions and variables are available to the stack application.

Helpers Public Members

10.7.1.1

Base64Decode Function

File

Helpers.h

WORD Base64Decode(

BYTE* cSourceData,

WORD wSourceLen,

BYTE* cDestData,

WORD wDestLen

);

Returns

Number of decoded bytes written to cDestData.

Description

Decodes a Base-64 array to its literal representation.

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.

Preconditions

None

Parameters

cSourceData wSourceLen cDestData

Description

Pointer to a string of Base-64 encoded data

Length of the Base-64 source data Maximum length that can be written to cDestData

Pointer to write the decoded data

10.7.1.2

Base64Encode Function

File

Helpers.h

WORD Base64Encode(

BYTE* cSourceData,

WORD wSourceLen,

BYTE* cDestData,

WORD wDestLen

);

Returns

Number of encoded bytes written to cDestData. This will always be a multiple of 4.

Description

Encodes a binary array to Base-64.

219

10.7 Helpers Microchip TCP/IP Stack Help Helpers Public Members

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.

Preconditions

None

Parameters

cSourceData wSourceLen cDestData

Description

Pointer to a string of binary data

Length of the binary source data Maximum length that can be written to cDestData

Pointer to write the Base-64 encoded data

10.7.1.3

btohexa_high Function

File

Helpers.h

BYTE btohexa_high(

BYTE b

);

Returns

The upper hexadecimal ASCII byte '0'-'9' or 'A'-'F'.

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

Description

the byte to convert

10.7.1.4

btohexa_low Function

File

Helpers.h

BYTE btohexa_low(

BYTE b

);

Returns

The lower hexadecimal ASCII byte '0'-'9' or 'A'-'F'.

Description

220)(0xAE) will return 'E'.

220

10.7 Helpers

Preconditions

None

Parameters

Microchip TCP/IP Stack Help Helpers Public Members

Description

the byte to convert

10.7.1.5

CalcIPChecksum Function

File

Helpers.h

WORD CalcIPChecksum(

BYTE* buffer,

WORD len

);

Returns

The calculated checksum.

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.

Internal

This function could be improved to do 32-bit sums on PIC32 platforms.

Preconditions

buffer is WORD aligned (even memory address) on 16- and 32-bit PICs.

Parameters

buffer count

Description

pointer to the data to be checksummed number of bytes to be checksummed

10.7.1.6

ExtractURLFields Function

File

Helpers.h

BYTE ExtractURLFields(

BYTE * vURL,

PROTOCOLS * protocol,

BYTE * vUsername,

WORD * wUsernameLen,

BYTE * vPassword,

WORD * wPasswordLen,

BYTE * vHostname,

WORD * wHostnameLen,

WORD * wPort,

BYTE * vFilePath,

WORD * wFilePathLen

);

221

10.7 Helpers Microchip TCP/IP Stack Help Helpers Public Members

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.

Description

Extracts all parameters from an URL string (ex: "http://admin:[email protected]: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

vURL protocol

Description

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

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.

vUsername

For the example URL provided in the function description, PROTOCOL_HTTP would be returned for this field.

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.

222

10.7 Helpers wUsernameLen vPassword wPasswordLen vHostname

Microchip TCP/IP Stack Help Helpers Public Members

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.

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.

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.

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 ( see page 229)() helper function to do this).

223

10.7 Helpers wHostnameLen wPort vFilePath wFilePathLen

Microchip TCP/IP Stack Help Helpers Public Members

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

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.

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.

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.

10.7.1.7

FormatNetBIOSName Function

File

Helpers.h

C void

FormatNetBIOSName(

BYTE Name[16]

);

Returns

None

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.

224

10.7 Helpers

Preconditions

None

Parameters

Name

Microchip TCP/IP Stack Help Helpers Public Members

Description

the string to format as a NetBIOS name. This parameter must have at least 16 bytes allocated.

10.7.1.8

GenerateRandomDWORD Function

File

Helpers.h

DWORD GenerateRandomDWORD();

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 ( see page 233)() 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.

Returns

Random 32-bit number.

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 ( see page

233)()/LFSRRand ( see page 233)() functions, the output is normalized (deskewed) in the hopes of meeting statistical

randomness tests.

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.

Preconditions

None

10.7.1.9

hexatob Function

File

Helpers.h

BYTE hexatob(

WORD_VAL AsciiChars

);

Returns

Resulting packed byte 0x00 - 0xFF.

Description

Converts a two-character ASCII hex string to a single packed byte.

225

10.7 Helpers

Preconditions

None

Parameters

AsciiChars

Microchip TCP/IP Stack Help Helpers Public Members

Description

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

10.7.1.10

leftRotateDWORD Function

File

Helpers.h

DWORD leftRotateDWORD(

DWORD val,

BYTE bits

);

Returns

Rotated DWORD value.

Description

This function rotates the bits in a 32-bit DWORD left by a specific number of bits.

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.

Preconditions

None

Parameters

val bits

Description

the DWORD to be rotated the number of bits by which to shift

10.7.1.11

leftRotateDWORD Macro

File

Helpers.h

#define

leftRotateDWORD(x, n) (((x) << (n)) | ((x) >> (32-(n))))

Description

Rotations are more efficient in C30 and C32

10.7.1.12

Replace Function

File

Helpers.h

226

10.7 Helpers Microchip TCP/IP Stack Help Helpers Public Members

SHORT Replace(

BYTE * vExpression,

ROM BYTE * vFind,

ROM BYTE * vReplacement,

WORD wMaxLen,

BOOL bSearchCaseInsensitive

);

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.

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.

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

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

vExpression vFind vReplacement wMaxLen bSearchCaseInsensitive

Description

Null terminated string to search and make replacements within.

Null terminated string to search for.

Null terminated string to replace all instances of vFind with.

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.

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

10.7.1.13

ROMStringToIPAddress Function

File

Helpers.h

BOOL ROMStringToIPAddress(

ROM BYTE* str,

IP_ADDR* IPAddress

);

227

10.7 Helpers Microchip TCP/IP Stack Help Helpers Public Members

Description

This function parses a dotted-quad decimal IP address string into an IP_ADDR struct. The output result is big-endian.

Remarks

This function is aliased to StringToIPAddress ( see page 229) on non-PIC18 platforms.

Preconditions

None

Parameters

str

IPAddress

Return Values

TRUE

FALSE

Description

Pointer to a dotted-quad IP address string

Pointer to IP_ADDR in which to store the result

Description

an IP address was successfully decoded no IP address could be found, or the format was incorrect

10.7.1.14

ROMStringToIPAddress Macro

File

Helpers.h

#define

ROMStringToIPAddress(a,b) StringToIPAddress((BYTE*)a,b)

Description

Non-ROM variant for C30 and C32

10.7.1.15

stricmppgm2ram Function

File

Helpers.h

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

a b

Description

Pinter to tring in RAM

Pointer to string in ROM

228

10.7 Helpers

Return Values

-1

Microchip TCP/IP Stack Help

Description

a < b a = b a > b

Helpers Public Members

10.7.1.16

StringToIPAddress Function

File

Helpers.h

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

str

IPAddress

Return Values

TRUE

FALSE

Description

Pointer to a dotted-quad IP address string

Pointer to IP_ADDR in which to store the result

Description

an IP address was successfully decoded no IP address could be found, or the format was incorrect

10.7.1.17

strupr Function

File

Helpers.h

C char

* strupr(

char

* s

);

Returns

Pointer to the initial string.

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

229

10.7 Helpers

Parameters

Microchip TCP/IP Stack Help

Description

the null-terminated string to be converted.

Helpers Public Members

10.7.1.18

strnchr Function

File

Helpers.h

C char

* strnchr(

const char

* searchString,

size_t count,

char

);

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.

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

searchString count c

Description

Pointer to a null terminated string to search. If count is less than the string size, then the string need not be null terminated.

Maximum number of characters to search before aborting.

Character to search for

10.7.1.19

swapl Function

File

Helpers.h

DWORD swapl(

DWORD v

);

Returns

The swapped version of v.

Description

Swaps the endian-ness of a DWORD.

Preconditions

None

230

10.7 Helpers

Parameters

Microchip TCP/IP Stack Help

Description

the DWORD to swap

10.7.1.20

swaps Function

File

Helpers.h

WORD swaps(

WORD v

);

Returns

The swapped version of v.

Description

Swaps the endian-ness of a WORD.

Preconditions

None

Parameters

Description

the WORD to swap

10.7.1.21

uitoa Function

File

Helpers.h

C void

uitoa(

WORD Value,

BYTE* Buffer

);

Returns

None

Description

Converts a 16-bit unsigned integer to a null-terminated decimal string.

Preconditions

None

Parameters

Value

Buffer

Description

The number to be converted

Pointer in which to store the converted string

Helpers Public Members

231

10.7 Helpers Microchip TCP/IP Stack Help Functions

10.7.1.22

ultoa Function

File

Helpers.h

C void

ultoa(

DWORD Value,

BYTE* Buffer

);

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

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

Value

Buffer

Description

The number to be converted

Pointer in which to store the converted string

10.7.1.23

UnencodeURL Function

File

Helpers.h

C void

UnencodeURL(

BYTE* URL

);

Returns

None

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

URL

Description

the null-terminated string to decode

232

10.7 Helpers Microchip TCP/IP Stack Help Functions

10.7.2

Functions

Functions

Name Description

LFSRRand ( see page 233) Returns a pseudo-random 16-bit unsigned integer in the range from 0 to 65535

(0x0000 to 0xFFFF).

LFSRSeedRand ( see page

233)

Seeds the LFSR random number generator invoked by the LFSRRand ( see page 233)() function. The prior seed is returned.

strncpy_m ( see page 234)

Copies multiple strings to a destination

Module

be seeded by calling the LFSRSeedRand ( see page 233)() function to generate the same sequence of random numbers

10.7.2.1

LFSRRand Function

File

Helpers.h

WORD LFSRRand();

Side Effects

The internal LFSR seed is updated so that the next call to LFSRRand() will return a different random number.

Returns

Random 16-bit unsigned integer.

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

as a prior string of calls.

The internal LFSR will repeat after 2^32-1 iterations.

Remarks

None

Preconditions

None

10.7.2.2

LFSRSeedRand Function

File

Helpers.h

DWORD LFSRSeedRand(

DWORD dwSeed

);

233

10.7 Helpers Microchip TCP/IP Stack Help Functions

Side Effects

None

Returns

The last seed in use. This can be saved and restored by a subsequent call to LFSRSeedRand() if you wish to use

LFSRRand ( see page 233)() 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 ( see page 233)() varies.

Description

Seeds the LFSR random number generator invoked by the LFSRRand ( see page 233)() function. The prior seed is

returned.

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.

Preconditions

None

Parameters

wSeed

Description

The new 32-bit seed value to assign to the LFSR.

10.7.2.3

strncpy_m Function

File

Helpers.h

size_t strncpy_m(

char

* destStr,

size_t destSize,

int

nStrings,

...

);

Returns

Length of the destination string, terminating 0 (if exists) not included

Description

Copies multiple strings to a destination but doesn't copy more than destSize characters. Useful where the destination is actually an array and an extra 0 won't be appended to overflow the buffer

Preconditions

• valid string pointers

• destSize should be > 0

Parameters

destStr destSize nStrings

Description

Pointer to a string to be initialized with the multiple strings provided as arguments.

the maximum size of the destStr field, that cannot be exceeded. An 0 won't be appended if the resulting size is > destSize number of string parameters to be copied into destStr

234

10.8 HTTP2 Server

...

Microchip TCP/IP Stack Help variable number of arguments

10.7.3

Variables

Module

dwLFSRRandSeed ( see page 235)

Variables

Name

Description

Default Random Number Generator seed. 0x41FE9F9E corresponds to calling

LFSRSeedRand ( see page 233)(1)

10.7.3.1

dwLFSRRandSeed Variable

File

Helpers.c

DWORD dwLFSRRandSeed = 0x41FE9F9E;

Description

Default Random Number Generator seed. 0x41FE9F9E corresponds to calling LFSRSeedRand ( see page 233)(1)

10.8

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

235

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Features 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 ( see page

251) callbacks), parses data submitted through forms (in HTTPExecuteGet ( see page 247) and HTTPExecutePost ( see page 248)) 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 ( see page 251) callback

functions defined in

CustomHTTPApp.c

. This file does not require modification by the programmer.

10.8.1

HTTP2 Features

Module

than 16 bytes), callbacks need only to call the appropriate TCPPut ( see page 549) function and return. For longer outputs,

Description

The HTTP2 web server module has many capabilities. The following topics will introduce these features and provide examples.

10.8.1.1

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:

<div

class

="examplebox code">~builddate~</div>

The associated callback will print the value into the web page:

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

236

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Features 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:

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

void

HTTPPrint_btn(WORD num)

{

// Determine which button

switch

(num)

{

case

num = BUTTON0_IO;

break

;

case

num = BUTTON1_IO;

break

;

case

num = BUTTON2_IO;

break

;

case

num = BUTTON3_IO;

break

;

default

num = 0;

}

// Print the output

(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

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:

<div

class

="examplebox code">~lcdtext~</div>

The following callback function handles the output, and manages its state for multiple calls:

void

HTTPPrint_lcdtext(

void

)

{

WORD len;

// Determine how many bytes we can write

len = TCPIsPutReady(sktHTTP);

// If just starting, set callbackPos

(curHTTP.callbackPos == 0)

curHTTP.callbackPos = 32;

237

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Features

// 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

(curHTTP.callbackPos == 16)

len -= TCPPutROMString(sktHTTP, (ROM BYTE*)"<br />");

(LCDText[32-curHTTP.callbackPos] == ' ' || LCDText[32-curHTTP.callbackPos] ==

'\0')

len -= TCPPutROMString(sktHTTP, (ROM BYTE*)" ");

else

len -= TCPPut(sktHTTP, LCDText[32-curHTTP.callbackPos]);

curHTTP.callbackPos--;

}

The initial call to TCPIsPutReady ( see page 546) determines how many bytes can be written to the buffer right now. The

TCPPut ( see page 549) 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:

At this time, dynamic variables are not recursive, so any variables located inside files included in this manner are not parsed.

10.8.1.2

HTTP2 Form Processing

Many applications need to accept ( see page 174) 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 ( see page 247) is implemented by the application developer to process this data

and perform any necessary actions. The functions HTTPGetArg ( see page 249) and HTTPGetROMArg ( see page 250)

provide an easy method to retrieve submitted values for processing.

The following example demonstrates a form to control several LEDs.

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 />

</form>

238

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Features

Suppose a user selects the checkboxes for LED 1 and LED3. The following string will be submitted to the server:

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

"led1\01\0led3\01\0\0"

It will then call HTTPExecuteGet ( see page 247) to process this input. To process this data, that callback needs to do

several things. First, it should call MPFSGetFilename ( see page 282) 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:

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

(!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");

(ptr)

LED1_IO = (*ptr == '1');

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

(ptr)

LED2_IO = (*ptr == '1');

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

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

page 252) and HTTPReadPostValue ( see page 253) 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.

To: <input type="text" name="to" maxlength="50" /><br />

Subject: <input type="text" name="subject" maxlength="50" /><br />

239

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Features

Message:<br />

</form>

Suppose a user enters the following data into this form:

To: [email protected]

Subject: Sent by a PIC

Message: I sent this message using my development board!

The HTTPExecutePost ( see page 248) function will be called with the following data still in the TCP buffer:

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 ( see page 252) and

HTTPReadPostValue ( see page 253) 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.

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.

(HTTPReadPostName(temp,16) == HTTP_READ_INCOMPLETE)

return

HTTP_IO_NEED_DATA;

// Save "to" values to curHTTP.data[0:49]

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

240

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Features

(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

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

see page 252) and HTTPReadPostValue ( see page 253)

functions, and also demonstrates using the need to use TCPIsGetReady ( see page 546), TCPGet ( see page 542), and

TCPGetArray ( see page 543) 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 ( see

page 253) to accomplish the callback. The HTTPPostLCD ( see page 97) 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.

10.8.1.3

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 ( see page 91) functionality is supported by two user-provided callback functions. The first, HTTPNeedsAuth

( see page 250), determines if the requested page requires valid credentials to proceed. The second, HTTPCheckAuth ( see page 247), 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

241

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Features

Requiring Authentication

When a request is first made, the function HTTPNeedsAuth ( see page 250) 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:

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:

BYTE HTTPNeedsAuth(BYTE* cFile)

{

// Compare to "/treasure" folder. Don't use strcmp here, because

// cFile has additional path info such as "/treasure/gold.htm"

(!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:

#define

HTTP_AUTH_ADMIN (0x00)

#define

HTTP_AUTH_OTHER (0x01)

BYTE HTTPNeedsAuth(BYTE* cFile)

{

// Return a specific code for admin users

(!memcmppgm2ram((

void

*)cFile, (ROM

void

*)"admin", 5))

return

HTTP_AUTH_ADMIN;

return

HTTP_AUTH_OTHER;

}

Validating Credentials

The HTTPCheckAuth ( see page 247) 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:

BYTE HTTPCheckAuth(BYTE* cUser, BYTE* cPass)

{

(!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 ( see page 250) above:

BYTE HTTPCheckAuth(BYTE* cUser, BYTE* cPass)

{

// Check for admin users first

(curHTTP.isAuthorized == HTTP_AUTH_ADMIN &&

!strcmppgm2ram((

char

*)cUser, (ROM

char

*)"admin") &&

242

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Features

!strcmppgm2ram((

char

*)cPass, (ROM

char

*)"s3cREt") )

return

0x80;

(!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 ( see page 247) 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.

10.8.1.4

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 ( see page 93) 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 ( see page 93) 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 ( see

page 247) callback using the HTTPGetArg ( see page 249) or HTTPGetROMArg ( see page 250) 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 ( see page 259)) 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 ( see page 93) can be set in HTTPExecuteGet ( see page 247) or HTTPExecutePost ( see page 248). 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:

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

243

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Public Members

10.8.1.5

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.

10.8.2

HTTP2 Public Members

Enumerations

Name

HTTP_IO_RESULT ( see page 246)

HTTP_READ_STATUS ( see page 246)

Functions

Description

Result states for execution callbacks

Result states for HTTPPostReadName and HTTPPostReadValue

Name

HTTPCheckAuth ( see page 247)

HTTPExecuteGet ( see page 247)

HTTPExecutePost ( see page 248)

HTTPGetArg ( see page

249)

HTTPGetROMArg ( see page 250)

HTTPNeedsAuth ( see page 250)

HTTPPrint_varname ( see page 251)

HTTPReadPostName ( see page 252)

HTTPReadPostValue ( see page 253)

HTTPURLDecode ( see page 254)

Description

Performs validation on a specific user name and password.

Processes GET form field variables and cookies.

Processes POST form variables and data.

Locates a form field value in a given data array.

Determines if a given file name requires authentication

Inserts dynamic content into a web page

Reads a name from a URL encoded string in the TCP buffer.

Reads a value from a URL encoded string in the TCP buffer.

Parses a string from URL encoding to plain-text.

Macros

Name

HTTPReadPostPair ( see page 253)

sktHTTP ( see page 255)

Description

Reads a name and value pair from a URL encoded string in the TCP buffer.

Access the current socket

244

10.8 HTTP2 Server Microchip TCP/IP Stack Help

Module

HTTP_STATUS httpStatus;

Structures

Name

HTTP_CONN ( see page

245)

Description

Stores extended state data for each connection

Variables

Name

curHTTP ( see page 245)

Description

Current HTTP connection state

Description

The following functions and variables are accessible or implemented by the stack application.

10.8.2.1

curHTTP Variable

File

HTTP2.c

HTTP_CONN curHTTP;

Description

Current HTTP connection state

10.8.2.2

HTTP_CONN Structure

File

HTTP2.h

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_FILE_TYPE fileType;

BYTE data[HTTP_MAX_DATA_LEN];

BYTE smPost;

} HTTP_CONN;

Members

DWORD byteCount;

DWORD nextCallback;

DWORD callbackID;

DWORD callbackPos;

BYTE * ptrData;

Description

How many bytes have been read so far

Byte index of the next callback

Callback ID to execute, also used as watchdog timer

Callback position indicator

Points to first free byte in data

HTTP2 Public Members

245

10.8 HTTP2 Server Microchip TCP/IP Stack Help

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;

Points to current read location

File pointer for the file being served

File pointer for any offset info being used

True if there were get or cookie arguments

0x00-0x79 on fail, 0x80-0xff on pass

Request method/status

File type to return with Content-Type

General purpose data buffer

POST state machine variable

Description

Stores extended state data for each connection

HTTP2 Public Members

10.8.2.3

HTTP_IO_RESULT Enumeration

File

HTTP2.h

C typedef enum

{

HTTP_IO_DONE = 0u,

HTTP_IO_NEED_DATA,

HTTP_IO_WAITING

} HTTP_IO_RESULT;

Members

HTTP_IO_DONE = 0u

HTTP_IO_NEED_DATA

HTTP_IO_WAITING

Description

Result states for execution callbacks

Description

Finished with procedure

More data needed to continue, call again later

Waiting for asynchronous process to complete, call again later

10.8.2.4

HTTP_READ_STATUS Enumeration

File

HTTP2.h

C typedef enum

{

HTTP_READ_OK = 0u,

HTTP_READ_TRUNCATED,

HTTP_READ_INCOMPLETE

} HTTP_READ_STATUS;

Members

HTTP_READ_OK = 0u

HTTP_READ_TRUNCATED

HTTP_READ_INCOMPLETE

Description

Read was successful

Buffer overflow prevented by truncating value

Entire object is not yet in the buffer. Try again later.

Description

Result states for HTTPPostReadName and HTTPPostReadValue

246

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Public Members

10.8.2.5

HTTPCheckAuth Function

File

HTTP2.h

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 ( see page 247), HTTPExecutePost ( see page 248), or HTTPPrint_varname ( see page 251)

callbacks.

Remarks

This function is only called when an Authorization header is encountered.

This function may NOT write to the TCP buffer.

Internal

See documentation in the TCP/IP Stack API or HTTP2.h for details.

Preconditions

None

Parameters

cUser cPass

Return Values

<= 0x79

>= 0x80

Description

the user name supplied by the client the password supplied by the client

Description

the credentials were rejected access is granted for this connection

10.8.2.6

HTTPExecuteGet Function

File

HTTP2.h

HTTP_IO_RESULT HTTPExecuteGet();

247

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Public Members

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 ( see page 249) and HTTPGetROMArg ( see page 250) 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 ( see page 248) and any HTTPPrint_varname ( see page 251) 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.

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.

Internal

See documentation in the TCP/IP Stack API or HTTP2.h for details.

Preconditions

None

Return Values

HTTP_IO_DONE

HTTP_IO_NEED_DATA

HTTP_IO_WAITING

Description

application is done processing this value may not be returned because more data will not become available the application is waiting for an asynchronous process to complete, and this function should be called again later

10.8.2.7

HTTPExecutePost Function

File

HTTP2.h

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 ( see page 542) or TCPGetArray ( see page 543) in

order to retrieve bytes. When this is done, curHTTP.byteCount MUST be updated to reflect how many bytes now remain.

The functions TCPFind (

see page 538), TCPFindString, TCPFindROMString, TCPFindArray ( see page 539), and

248

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Public Members

TCPFindROMArray ( see page 541) may be helpful to locate data in the TCP buffer.

In general, data submitted from web forms via POST is URL encoded. The HTTPURLDecode ( see page 254) 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 ( see page

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

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.

Internal

See documentation in the TCP/IP Stack API or HTTP2.h for details.

Preconditions

None

Return Values

HTTP_IO_DONE

HTTP_IO_NEED_DATA

HTTP_IO_WAITING

Description

application is done processing more data is needed to continue, and this function should be called again later the application is waiting for an asynchronous process to complete, and this function should be called again later

10.8.2.8

HTTPGetArg Function

File

HTTP2.h

BYTE* HTTPGetArg(

BYTE* cData,

BYTE* cArg

);

Returns

A pointer to the argument value, or NULL if not found.

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.

249

10.8 HTTP2 Server Microchip TCP/IP Stack Help

Preconditions

The data array has a valid series of null terminated name/value pairs.

Parameters

data arg

Description

the buffer to search the name of the argument to find

HTTP2 Public Members

10.8.2.9

HTTPGetROMArg Function

File

HTTP2.h

BYTE* HTTPGetROMArg(

BYTE* cData,

ROM BYTE* cArg

);

Returns

A pointer to the argument value, or NULL if not found.

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.

Remarks

This function is aliased to HTTPGetArg ( see page 249) on non-PIC18 platforms.

Preconditions

The data array has a valid series of null terminated name/value pairs.

Parameters

data arg

Description

the buffer to search the name of the argument to find

10.8.2.10

HTTPNeedsAuth Function

File

HTTP2.h

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

250

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Public Members 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 ( see page 247) and any of the HTTPExecuteGet ( see page 247), HTTPExecutePost ( see page

248), or HTTPPrint_varname ( see page 251) callbacks.

Remarks

This function may NOT write to the TCP buffer.

Internal

See documentation in the TCP/IP Stack API or HTTP2.h for details.

Preconditions

None

Parameters

cFile

Return Values

<= 0x79

>= 0x80

Description

the name of the file being requested

Description

valid authentication is required access is granted for this connection

10.8.2.11

HTTPPrint_varname Function

File

HTTP2.h

C void

HTTPPrint_varname(

WORD wParam1,

WORD wParam2,

...

);

Returns

None

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

page 546), TCPPut ( see page 549), TCPPutArray ( see page 550), TCPPutString ( see page 552), TCPPutROMArray

( see page 550), and TCPPutROMString ( see page 551).

Before calling, the HTTP2 server guarantees that at least HTTP_MIN_CALLBACK_FREE ( see page 259) 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

251

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Public Members 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.

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.

Preconditions

None

Parameters

wParam1 wParam2

...

Description

first parameter passed in the dynamic variable (if any) second parameter passed in the dynamic variable (if any) additional parameters as necessary

10.8.2.12

HTTPReadPostName Function

File

HTTP2.h

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

( see page 248) 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

cData wLen

Return Values

HTTP_READ_OK

Description

where to store the name once it is read how many bytes can be written to cData

Description

name was successfully read

252

10.8 HTTP2 Server

HTTP_READ_TRUNCTATED

HTTP_READ_INCOMPLETE

Microchip TCP/IP Stack Help HTTP2 Public Members entire name could not fit in the buffer, so the value was truncated and data has been lost entire name was not yet in the buffer, so call this function again later to retrieve

10.8.2.13

HTTPReadPostPair Macro

File

HTTP2.h

#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 ( see page 248) 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.

Remarks

This function is aliased to HTTPReadPostValue ( see page 253), since they effectively perform the same task. The name is

provided only for completeness.

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

cData wLen

Return Values

HTTP_READ_OK

HTTP_READ_TRUNCTATED

HTTP_READ_INCOMPLETE

Description

where to store the name and value strings once they are read how many bytes can be written to cData

Description

name and value were successfully read entire name and value could not fit in the buffer, so input was truncated and data has been lost entire name and value was not yet in the buffer, so call this function again later to retrieve

10.8.2.14

HTTPReadPostValue Function

File

HTTP2.h

HTTP_READ_STATUS HTTPReadPostValue(

253

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Public Members

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

( see page 248) 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

cData wLen

Return Values

HTTP_READ_OK

HTTP_READ_TRUNCTATED

HTTP_READ_INCOMPLETE

Description

where to store the value once it is read how many bytes can be written to cData

Description

value was successfully read entire value could not fit in the buffer, so the value was truncated and data has been lost entire value was not yet in the buffer, so call this function again later to retrieve

10.8.2.15

HTTPURLDecode Function

File

HTTP2.h

BYTE* HTTPURLDecode(

BYTE* cData

);

Returns

A pointer to the last null terminator in data, which is also the first free byte for new data.

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.

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.

254

10.8 HTTP2 Server Microchip TCP/IP Stack Help

Preconditions

The data parameter is null terminated and has at least one extra byte free.

Parameters

cData

Description

The string which is to be decoded in place.

HTTP2 Stack Members

10.8.2.16

sktHTTP Macro

File

HTTP2.h

#define

sktHTTP httpStubs[curHTTPID].socket

// Access the current socket

Description

Access the current socket

10.8.3

HTTP2 Stack Members

Functions

Name

HTTPInit ( see page 255)

HTTPServer ( see page

256)

Module

HTTPInit ( see page 255)() must already be called.

Description

Initializes the HTTP server module.

Performs periodic tasks for the HTTP2 module.

Description

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.

10.8.3.1

HTTPInit Function

File

HTTP2.h

C void

HTTPInit();

Returns

None

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.

Remarks

This function is called only one during lifetime of the application.

255

10.8 HTTP2 Server

Preconditions

TCP must already be initialized.

Section

Function Prototypes

Microchip TCP/IP Stack Help HTTP2 Internal Members

10.8.3.2

HTTPServer Function

File

HTTP2.h

C void

HTTPServer();

Returns

None

Description

Browses through each open connection and attempts to process any pending operations.

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.

Preconditions

10.8.4

HTTP2 Internal Members

Enumerations

Name

HTTP_FILE_TYPE ( see page 258)

HTTP_STATUS ( see page

259)

Description

File type definitions

Supported Commands and Server Response Codes

SM_HTTP2 ( see page 267) Basic HTTP Connection State Machine

Functions

Name

HTTPHeaderParseAuthorization

( see page 261)

Description

Parses the "Authorization:" header for a request and verifies the credentials.

HTTPHeaderParseContentLength

( see page 262)

Parses the "Content-Length:" header for a request.

HTTPHeaderParseCookie ( see page 262)

Parses the "Cookie:" headers for a request and stores them as GET variables.

HTTPHeaderParseLookup ( see page 263)

Calls the appropriate header parser based on the index of the header that was read from the request.

HTTPIncFile ( see page 263)

Writes a file byte-for-byte to the currently loaded TCP socket.

HTTPLoadConn ( see page 264) Switches the currently loaded connection for the HTTP2 module.

HTTPMPFSUpload ( see page

264)

Saves a file uploaded via POST as the new MPFS image in EEPROM or external Flash.

256

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Internal Members

HTTPProcess ( see page 265)

Performs any pending operations for the currently loaded HTTP connection.

HTTPReadTo ( see page 265)

Reads to a buffer until a specified delimiter character.

HTTPSendFile ( see page 267)

Serves up the next chunk of curHTTP ( see page 245)'s file, up to a)

available TX FIFO space or b) the next callback index, whichever comes first.

Macros

Name

HTTP_CACHE_LEN ( see page 258)

HTTP_MAX_DATA_LEN ( see page 259)

Description

Max lifetime (sec) of static responses as string

Define the maximum data length for reading cookie and GET/POST arguments (bytes)

HTTP_MAX_HEADER_LEN ( see page 259)

Set to length of longest string above

HTTP_MIN_CALLBACK_FREE

( see page 259)

Define the minimum number of bytes free in the TX FIFO before executing callbacks

HTTP_PORT ( see page 259) Define the listening port for the HTTP server

HTTP_TIMEOUT ( see page

261)

Max time (sec) to await more data before timing out and disconnecting the socket

HTTPS_PORT ( see page

266)

smHTTP ( see page 268)

RESERVED_HTTP_MEMORY

( see page 268)

Define the listening port for the HTTPS server (if

STACK_USE_SSL_SERVER is enabled)

Access the current state machine

Macro indicating how much RAM to allocate on an ethernet controller to store

HTTP state data.

Module

curHTTPID ( see page 257) ID of the currently loaded HTTP_CONN ( see page 245)

Structures

Name

HTTP_STUB ( see page

260)

Description

HTTP Connection Struct Stores partial state data for each connection Meant for storage in fast access RAM

Variables

Name Description

httpContentTypes ( see page 261)

Content-type strings corresponding to HTTP_FILE_TYPE ( see page 258)

httpFileExtensions ( see page 261)

HTTPRequestHeaders ( see page 266)

Header strings for which we'd like to parse

HTTPResponseHeaders ( see page 266)

Initial response strings (Corresponding to HTTP_STATUS ( see page 259))

httpStubs ( see page 267)

HTTP stubs with state machine and socket

Description

The following functions and variables are designated as internal to the HTTP2 module.

10.8.4.1

curHTTPID Variable

File

HTTP2.c

257

10.8 HTTP2 Server Microchip TCP/IP Stack Help

BYTE curHTTPID;

Description

ID of the currently loaded HTTP_CONN ( see page 245)

HTTP2 Internal Members

10.8.4.2

HTTP_CACHE_LEN Macro

File

HTTP2.h

#define

HTTP_CACHE_LEN ("600")

// Max lifetime (sec) of static responses as string

Description

Max lifetime (sec) of static responses as string

10.8.4.3

HTTP_FILE_TYPE Enumeration

File

HTTP2.h

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;

Members

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

Description

File type definitions

Description

File is a text document

File is HTML (extension .htm)

File is HTML (extension .html)

File is HTML (extension .cgi)

File is XML (extension .xml)

File is stylesheet (extension .css)

File is GIF image (extension .gif)

File is PNG image (extension .png)

File is JPG image (extension .jpg)

File is java (extension .java)

File is audio (extension .wav)

File type is unknown

258

10.8 HTTP2 Server Microchip TCP/IP Stack Help

10.8.4.4

HTTP_MAX_DATA_LEN Macro

File

TCPIP MRF24W.h

#define

HTTP_MAX_DATA_LEN (100u)

Description

Define the maximum data length for reading cookie and GET/POST arguments (bytes)

10.8.4.5

HTTP_MAX_HEADER_LEN Macro

File

HTTP2.c

#define

HTTP_MAX_HEADER_LEN (15u)

Description

Set to length of longest string above

10.8.4.6

HTTP_MIN_CALLBACK_FREE Macro

File

TCPIP MRF24W.h

#define

HTTP_MIN_CALLBACK_FREE (16u)

Description

Define the minimum number of bytes free in the TX FIFO before executing callbacks

10.8.4.7

HTTP_PORT Macro

File

TCPIP MRF24W.h

#define

HTTP_PORT (80u)

Description

Define the listening port for the HTTP server

10.8.4.8

HTTP_STATUS Enumeration

File

HTTP2.h

HTTP2 Internal Members

259

10.8 HTTP2 Server Microchip TCP/IP Stack Help

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;

Members

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

Description

GET command is being processed

POST command is being processed

400 Bad Request will be returned

401 Unauthorized will be returned

404 Not Found will be returned

414 Request-URI Too Long will be returned

500 Internal Server Error will be returned

501 Not Implemented (not a GET or POST command)

Show the MPFS Upload form

An MPFS Upload is being processed

An MPFS Upload was successful

An MPFS Upload was not a valid image

302 Redirect will be returned

403 Forbidden is returned, indicating SSL is required

Description

Supported Commands and Server Response Codes

HTTP2 Internal Members

10.8.4.9

HTTP_STUB Structure

File

HTTP2.h

C typedef struct

{

SM_HTTP2 sm;

TCP_SOCKET socket;

} HTTP_STUB;

Members

SM_HTTP2 sm;

TCP_SOCKET socket;

Description

Current connection state

Socket being served

Description

HTTP Connection Struct Stores partial state data for each connection Meant for storage in fast access RAM

260

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Internal Members

10.8.4.10

HTTP_TIMEOUT Macro

File

HTTP2.h

#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

10.8.4.11

httpContentTypes Variable

File

HTTP2.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 ( see page 258)

10.8.4.12

httpFileExtensions Variable

File

HTTP2.c

ROM

char

* ROM httpFileExtensions[HTTP_UNKNOWN+1] = { "txt", "htm", "html", "cgi", "xml",

"css", "gif", "png", "jpg", "cla", "wav", "\0\0\0" };

Section

File and Content Type Settings

************************************************************************

File type extensions corresponding to HTTP_FILE_TYPE

10.8.4.13

HTTPHeaderParseAuthorization Function

File

HTTP2.c

C static void

HTTPHeaderParseAuthorization();

Returns

None

261

10.8 HTTP2 Server Microchip TCP/IP Stack Help HTTP2 Internal Members

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 ( see page 247) is called from

CustomHTTPApp.c to determine if the credentials are acceptable.

The return value of HTTPCheckAuth ( see page 247) is saved in curHTTP.isAuthorized for later use by the application.

Remarks

This function is ony available when HTTP_USE_AUTHENTICATION is defined.

Preconditions

None

10.8.4.14

HTTPHeaderParseContentLength Function

File

HTTP2.c

C static void

HTTPHeaderParseContentLength();

Returns

None

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.

Remarks

This function is ony available when HTTP_USE_POST is defined.

Preconditions

None

10.8.4.15

HTTPHeaderParseCookie Function

File

HTTP2.c

C static void

HTTPHeaderParseCookie();

Returns

None

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 ( see page 249)() and HTTPGetROMArg

( see page 250)() functions.

Remarks

This function is ony available when HTTP_USE_COOKIES is defined.

262

10.8 HTTP2 Server

Preconditions

None

Microchip TCP/IP Stack Help HTTP2 Internal Members

10.8.4.16

HTTPHeaderParseLookup Function

File

HTTP2.c

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

Return Values

TRUE

FALSE

Section

Function Prototypes

Description

the index of the string found in HTTPRequestHeaders ( see page 266)

Description

the end of the file was reached and reading is done more data remains to be read

10.8.4.17

HTTPIncFile Function

File

HTTP2.h

C void

HTTPIncFile(

ROM BYTE* cFile

);

Returns

None

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.

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

263

10.8 HTTP2 Server the rest.

Preconditions

None

Parameters

cFile

Microchip TCP/IP Stack Help

Description

the name of the file to be sent

HTTP2 Internal Members

10.8.4.18

HTTPLoadConn Function

File

HTTP2.c

C static void

HTTPLoadConn(

BYTE hHTTP

);

Returns

None

Description

Saves the currently loaded HTTP connection back to Ethernet buffer RAM, then loads the selected connection into curHTTP

( see page 245) in local RAM for processing.

Preconditions

None

Parameters

hHTTP

Description

the connection ID to load

10.8.4.19

HTTPMPFSUpload Function

File

HTTP2.c

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.

Remarks

This function is only available when MPFS uploads are enabled and the MPFS image is stored in EEPROM.

Internal

After the headers, the first line from the form will be the MIME separator. Following that is more headers about the file, which are discarded. After another CRLFCRLF pair the file data begins, which is read 16 bytes at a time and written to external memory.

Preconditions

MPFSFormat ( see page 279)() has been called.

264

10.8 HTTP2 Server

Return Values

HTTP_IO_DONE

HTTP_IO_NEED_DATA

Microchip TCP/IP Stack Help

Description

on success if more data is still expected

10.8.4.20

HTTPProcess Function

File

HTTP2.c

C static void

HTTPProcess();

Returns

None

Description

Performs any pending operations for the currently loaded HTTP connection.

Preconditions

HTTPInit ( see page 255)() and HTTPLoadConn ( see page 264)() have been called.

HTTP2 Internal Members

10.8.4.21

HTTPReadTo Function

File

HTTP2.c

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 ( see page

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

cDelim cData wLen

Description

the character at which to stop reading, or NULL to read to the end of the buffer where to store the data being read how many bytes can be written to cData

265

10.8 HTTP2 Server

Return Values

HTTP_READ_OK

HTTP_READ_TRUNCTATED

HTTP_READ_INCOMPLETE

Microchip TCP/IP Stack Help HTTP2 Internal Members

Description

data was successfully read entire data could not fit in the buffer, so the data was truncated and data has been lost delimiter character was not found

10.8.4.22

HTTPRequestHeaders Variable

File

HTTP2.c

ROM

char

* ROM HTTPRequestHeaders[] = { "Cookie:", "Authorization:", "Content-Length:" };

Description

Header strings for which we'd like to parse

10.8.4.23

HTTPResponseHeaders Variable

File

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

  <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 ( see page 259))

10.8.4.24

HTTPS_PORT Macro

File

TCPIP MRF24W.h

266

10.8 HTTP2 Server Microchip TCP/IP Stack Help

#define

HTTPS_PORT (443u)

Description

Define the listening port for the HTTPS server (if STACK_USE_SSL_SERVER is enabled)

HTTP2 Internal Members

10.8.4.25

HTTPSendFile Function

File

HTTP2.c

C static

BOOL HTTPSendFile();

Description

Serves up the next chunk of curHTTP ( see page 245)'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

TRUE

FALSE

Description

the end of the file was reached and reading is done more data remains to be read

10.8.4.26

httpStubs Variable

File

HTTP2.c

HTTP_STUB httpStubs[MAX_HTTP_CONNECTIONS];

Description

HTTP stubs with state machine and socket

10.8.4.27

SM_HTTP2 Enumeration

File

HTTP2.h

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,

267

10.9 ICMP

SM_HTTP_DISCONNECT

} SM_HTTP2;

Members

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

Description

Basic HTTP Connection State Machine

Microchip TCP/IP Stack Help

Description

Socket is idle

Parses the first line for a file name and GET args

Reads and parses headers one at a time

Validates the current authorization state

Invokes user callback for GET args or cookies

Invokes user callback for POSTed data

Begins the process of returning data

Sends any required headers for the response

Adds any cookies to the response

Serves the actual content

Invokes a dynamic variable callback

Disconnects the server and closes all files

10.8.4.28

smHTTP Macro

File

HTTP2.c

#define

smHTTP httpStubs[curHTTPID].sm

// Access the current state machine

Description

Access the current state machine

10.8.4.29

RESERVED_HTTP_MEMORY Macro

File

HTTP2.h

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

10.9

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.

268

10.9 ICMP Microchip TCP/IP Stack Help ICMP Public Members

10.9.1

ICMP Public Members

Functions

Name

ICMPBeginUsage ( see page 269)

ICMPSendPing ( see page

270)

ICMPSendPingToHost ( see page 270)

ICMPSendPingToHostROM

( see page 271)

ICMPGetReply ( see page

271)

ICMPEndUsage ( see page

272)

Description

Claims ownership of the ICMP module.

None

Begins the process of transmitting an ICMP echo request. This normally involves an ARP resolution procedure first.

None

Gives up ownership of the ICMP module.

Macros

Name

ICMPSendPingToHostROM

( see page 272)

Module

ICMP ( see page 268)

Description

This is macro ICMPSendPingToHostROM.

Description

The following functions and variables are accessible or implemented by the stack application.

10.9.1.1

ICMPBeginUsage Function

File

ICMP.h

BOOL ICMPBeginUsage();

Side Effects

None

Returns

TRUE: You have successfully gained ownership of the ICMP client module and can now use the ICMPSendPing ( see

page 270)() and ICMPGetReply ( see page 271)() functions. FALSE: Some other application is using the ICMP client

module. Calling ICMPSendPing ( see page 270)() will corrupt the other application's ping result.

269

10.9 ICMP

Description

Claims ownership of the ICMP module.

Remarks

None

Preconditions

None

Microchip TCP/IP Stack Help ICMP Public Members

10.9.1.2

ICMPSendPing Function

File

ICMP.h

C void

ICMPSendPing(

DWORD dwRemoteIP

);

Side Effects

None

Returns

Begins the process of transmitting an ICMP echo request. This normally involves an ARP resolution procedure first.

Description

None

Remarks

None

Preconditions

ICMPBeginUsage ( see page 269)() returned TRUE

Parameters

dwRemoteIP

Description

IP Address ( see page 152) to ping. Must be stored big endian. Ex.

192.168.0.1 should be passed as 0x0100A8C0.

10.9.1.3

ICMPSendPingToHost Function

File

ICMP.h

C void

ICMPSendPingToHost(

BYTE * szRemoteHost

);

Side Effects

None

Returns

Begins the process of transmitting an ICMP echo request. This normally involves an ARP resolution procedure first.

270

10.9 ICMP Microchip TCP/IP Stack Help ICMP Public Members

Description

None

Remarks

None

Preconditions

ICMPBeginUsage ( see page 269)() returned TRUE

Parameters

szRemoteHost

Description

Host name to ping. Must be stored in RAM if being called by PIC18. Ex. www.microchip.com

10.9.1.4

ICMPSendPingToHostROM Function

File

ICMP.h

C void

ICMPSendPingToHostROM(

ROM BYTE * szRemoteHost

);

Side Effects

None

Returns

None

Description

Begins the process of transmitting an ICMP echo request. This normally involves an ARP resolution procedure first.

Remarks

None

Preconditions

ICMPBeginUsage ( see page 269)() returned TRUE

Parameters

szRemoteHost

Description

Host name to ping. Must be stored in ROM. Should only be called by PIC18.

Ex. www.microchip.com

10.9.1.5

ICMPGetReply Function

File

ICMP.h

LONG ICMPGetReply();

Side Effects

None

271

10.9 ICMP Microchip TCP/IP Stack Help ICMP Internal Members

Returns

-3: Could not resolve hostname (DNS timeout or hostname invalid) -2: No response received yet -1: Operation timed out

(longer than ICMP_TIMEOUT ( see page 275)) has elapsed. >=0: Number of TICKs that elapsed between initial ICMP

transmission and reception of a valid echo.

Description

None

Remarks

None

Preconditions

ICMPBeginUsage ( see page 269)() returned TRUE and ICMPSendPing ( see page 270)() was called

10.9.1.6

ICMPEndUsage Function

File

ICMP.h

C void

ICMPEndUsage();

Side Effects

None

Returns

Your ownership of the ICMP module is released. You can no longer use ICMPSendPing ( see page 270)().

Description

Gives up ownership of the ICMP module.

Remarks

None

Preconditions

ICMPBeginUsage ( see page 269)() was called by you and it returned TRUE.

10.9.1.7

ICMPSendPingToHostROM Macro

File

ICMP.h

#define

ICMPSendPingToHostROM(a) ICMPSendPingToHost((BYTE*)(a))

Description

This is macro ICMPSendPingToHostROM.

272

10.9 ICMP Microchip TCP/IP Stack Help ICMP Internal Members

10.9.2

ICMP Internal Members

Functions

Name

ICMPProcess ( see page

273)

Macros

Name

ICMP_TIMEOUT ( see page 275)

Module

ICMP ( see page 268)

Description

None

Description

ICMP Timeout Value

Structures

Name

ICMP_PACKET ( see page

274)

Description

ICMP Packet Structure

Variables

Name Description

ICMPFlags ( see page 274) ICMP Flag structure

ICMPState ( see page 274)

ICMP State Machine Enumeration

ICMPTimer ( see page 275) ICMP tick timer variable

StaticVars ( see page 275)

ICMP Static Variables

wICMPSequenceNumber ( see page 276)

ICMP Sequence Number

Description

The following functions and variables are designated as internal to the ICMP module.

10.9.2.1

ICMPProcess Function

File

ICMP.h

C void

ICMPProcess(

NODE_INFO * remote,

WORD len

);

Side Effects

None

Returns

Generates an echo reply, if requested Validates and sets ICMPFlags.bReplyValid if a correct ping response to one of ours is received.

Description

None

273

10.9 ICMP Microchip TCP/IP Stack Help ICMP Internal Members

Remarks

None

Preconditions

MAC buffer contains ICMP type packet.

Parameters

*remote len

Description

Pointer to a NODE_INFO structure of the ping requester

Count of how many bytes the ping header and payload are in this IP packet

10.9.2.2

ICMPFlags Variable

File

ICMP.c

C struct

{

unsigned char

bICMPInUse : 1;

unsigned char

bReplyValid : 1;

unsigned char

bRemoteHostIsROM : 1;

} ICMPFlags;

Members

unsigned char bICMPInUse : 1; unsigned char bReplyValid : 1; unsigned char bRemoteHostIsROM : 1;

Description

ICMP Flag structure

Description

Indicates that the ICMP Client is in use

Indicates that a correct Ping response to one of our pings was received

Indicates that a remote host name was passed as a ROM pointer argument

10.9.2.3

ICMP_PACKET Structure

File

ICMP.c

C typedef struct

{

BYTE vType;

BYTE vCode;

WORD wChecksum;

WORD wIdentifier;

WORD wSequenceNumber;

WORD wData;

} ICMP_PACKET;

Description

ICMP Packet Structure

10.9.2.4

ICMPState Variable

File

ICMP.c

274

10.9 ICMP

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

Microchip TCP/IP Stack Help

10.9.2.5

ICMP_TIMEOUT Macro

File

ICMP.c

#define

ICMP_TIMEOUT (4ul*TICK_SECOND)

Description

ICMP Timeout Value

10.9.2.6

ICMPTimer Variable

File

ICMP.c

DWORD ICMPTimer;

Description

ICMP tick timer variable

10.9.2.7

StaticVars Variable

File

ICMP.c

C union

{

union

{

ROM BYTE * szROM;

BYTE * szRAM;

} RemoteHost;

NODE_INFO ICMPRemote;

} StaticVars;

Description

ICMP Static Variables

ICMP Internal Members

275

MPFS2 Public Members 10.10 MPFS2 Microchip TCP/IP Stack Help

10.9.2.8

wICMPSequenceNumber Variable

File

ICMP.c

WORD wICMPSequenceNumber;

Description

ICMP Sequence Number

10.10

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 ( see page 64) 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 ( see page 65) is described in the MPFS2 Utility documentation. Uploading

images via HTTP can be accomplished as described in the Getting Started ( see page 79) 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 ( see page 279) 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.

276

10.10 MPFS2 Microchip TCP/IP Stack Help

10.10.1

MPFS2 Public Members

Enumerations

Name

MPFS_SEEK_MODE ( see page 278)

Description

Indicates the method for MPFSSeek ( see page 288)

Functions

Name Description

MPFSClose ( see page 279) Closes a file.

MPFSFormat ( see page

279)

Prepares the MPFS image for writing.

MPFSGet ( see page 280)

Reads a byte from a file.

Reads a series of bytes from a file.

MPFSGetArray ( see page

280)

MPFSGetBytesRem ( see page 281)

Determines how many bytes remain to be read.

Determines the ending address of a file.

MPFSGetEndAddr ( see page 281)

MPFSGetFilename ( see page 282)

MPFSGetFlags ( see page

282)

Reads the file name of a file that is already open.

Reads a file's flags.

MPFSGetID ( see page 283) Determines the ID in the FAT for a file.

MPFSGetLong ( see page

283)

Reads a DWORD or Long value from the MPFS.

MPFSGetMicrotime ( see page 284)

Reads the microtime portion of a file's timestamp.

Determines the current position in the file

MPFSGetPosition ( see page 284)

MPFSGetSize ( see page

284)

MPFSGetStartAddr ( see page 285)

Reads the size of a file.

Reads the starting address of a file.

MPFSGetTimestamp ( see page 285)

Reads the timestamp for the specified file.

MPFSOpen ( see page 286) Opens a file in the MPFS2 file system.

Quickly re-opens a file.

MPFSOpenID ( see page

286)

MPFSOpenROM ( see page 287)

Opens a file in the MPFS2 file system.

MPFSPutArray ( see page

287)

Writes an array of data to the MPFS image.

MPFSSeek ( see page 288) Moves the current read pointer to a new location.

MPFSPutEnd ( see page

288)

Finalizes an MPFS writing operation.

Macros

Name

MPFS_INVALID ( see page

278)

Description

Indicates a position pointer is invalid

MPFS2 Public Members

277

10.10 MPFS2 Microchip TCP/IP Stack Help

Module

Indicates the method for MPFSSeek ( see page 288)

Types

MPFS_INVALID_HANDLE

( see page 278)

Indicates that a handle is not valid

Name Description

MPFS_HANDLE ( see page

278)

MPFS Handles are currently stored as BYTEs

Description

The following functions and variables are accessible by the stack application.

MPFS2 Public Members

10.10.1.1

MPFS_HANDLE Type

File

MPFS2.h

C typedef

BYTE MPFS_HANDLE;

Description

MPFS Handles are currently stored as BYTEs

10.10.1.2

MPFS_INVALID Macro

File

MPFS2.h

#define

MPFS_INVALID (0xffffffffu)

// Indicates a position pointer is invalid

Description

Indicates a position pointer is invalid

10.10.1.3

MPFS_INVALID_HANDLE Macro

File

MPFS2.h

#define

MPFS_INVALID_HANDLE (0xffu)

// Indicates that a handle is not valid

Description

Indicates that a handle is not valid

10.10.1.4

MPFS_SEEK_MODE Enumeration

File

MPFS2.h

278

10.10 MPFS2 Microchip TCP/IP Stack Help

C typedef enum

{

MPFS_SEEK_START = 0u,

MPFS_SEEK_END,

MPFS_SEEK_FORWARD,

MPFS_SEEK_REWIND

} MPFS_SEEK_MODE;

Members

MPFS_SEEK_START = 0u

MPFS_SEEK_END

MPFS_SEEK_FORWARD

MPFS_SEEK_REWIND

Description

Seek forwards from the front of the file

Seek backwards from the end of the file

Seek forward from the current position

See backwards from the current position

Description

MPFS2 Public Members

10.10.1.5

MPFSClose Function

File

MPFS2.h

C void

MPFSClose(

);

Returns

None

Description

Closes a file and releases its stub back to the pool of available handles.

Preconditions

None

Parameters

MPFS_HANDLE MPFSFormat();

Description

the file handle to be closed

10.10.1.6

MPFSFormat Function

File

MPFS2.h

Returns

An MPFS handle that can be used for MPFSPut commands, or MPFS_INVALID_HANDLE ( see page 278) when the

EEPROM failed to initialize for writing.

Description

Prepares the MPFS image for writing and locks the image so that other processes may not access it.

279

10.10 MPFS2 Microchip TCP/IP Stack Help MPFS2 Public Members

Remarks

In order to prevent misreads, the MPFS will be inaccessible until MPFSClose ( see page 279) is called. This function is not

available when the MPFS is stored in internal Flash program memory.

Preconditions

None

10.10.1.7

MPFSGet Function

File

MPFS2.h

BOOL MPFSGet(

BYTE* c

);

Description

Reads a byte from a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

Return Values

TRUE

FALSE

Description

the file handle from which to read

Where to store the byte that was read

Description

The byte was successfully read

No byte was read because either the handle was invalid or the end of the file has been reached.

10.10.1.8

MPFSGetArray Function

File

MPFS2.h

WORD MPFSGetArray(

BYTE* cData,

WORD wLen

);

Returns

The number of bytes successfully read. If this is less than wLen, an EOF occurred while attempting to read.

Description

Reads a series of bytes from a file.

Preconditions

The file handle referenced by hMPFS is already open.

280

10.10 MPFS2

Parameters

cData wLen

Microchip TCP/IP Stack Help

Description

the file handle from which to read where to store the bytes that were read how many bytes to read

10.10.1.9

MPFSGetBytesRem Function

File

MPFS2.h

DWORD MPFSGetBytesRem(

);

Returns

The number of bytes remaining in the file as a DWORD

Description

Determines how many bytes remain to be read.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

MPFS_PTR MPFSGetEndAddr(

Description

the file handle from which to read the metadata

10.10.1.10

MPFSGetEndAddr Function

File

MPFS2.h

);

Returns

The address just after the file ends (start address of next file)

Description

Determines the ending address of a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

Description

the file handle from which to read the metadata

MPFS2 Public Members

281

10.10 MPFS2 Microchip TCP/IP Stack Help

10.10.1.11

MPFSGetFilename Function

File

MPFS2.h

BOOL MPFSGetFilename(

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

cName wLen

Return Values

TRUE

FALSE

Description

the file handle from which to determine the file name where to store the name of the file the maximum length of data to store in cName

Description

the file name was successfully located the file handle provided is not currently open

10.10.1.12

MPFSGetFlags Function

File

MPFS2.h

WORD MPFSGetFlags(

);

Returns

The flags that were associated with the file

Description

Reads a file's flags.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

Description

the file handle from which to read the metadata

MPFS2 Public Members

282

10.10 MPFS2 Microchip TCP/IP Stack Help MPFS2 Public Members

10.10.1.13

MPFSGetID Function

File

MPFS2.h

WORD MPFSGetID(

Use this function in association with MPFSOpenID ( see page 286) to quickly access file without permanently reserving a

);

Returns

The ID in the FAT for this file

Description

Determines the ID in the FAT for a file.

Remarks

file handle.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

Description

the file handle from which to read the metadata

10.10.1.14

MPFSGetLong Function

File

MPFS2.h

BOOL MPFSGetLong(

DWORD* ul

);

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.

Description

Reads a DWORD or Long value from the MPFS.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

Description

the file handle from which to read where to store the DWORD or long value that was read

283

10.10 MPFS2 Microchip TCP/IP Stack Help MPFS2 Public Members

10.10.1.15

MPFSGetMicrotime Function

File

MPFS2.h

DWORD MPFSGetMicrotime(

);

Returns

The microtime that was read as a DWORD

Description

Reads the microtime portion of a file's timestamp.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

Description

the file handle from which to read the metadata

10.10.1.16

MPFSGetPosition Function

File

MPFS2.h

DWORD MPFSGetPosition(

The position in the file as a DWORD (or MPFS_PTR ( see page 291))

);

Returns

Description

Determines the current position in the file

Remarks

Calling MPFSSeek ( see page 288)(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.)

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

Description

the file handle for which to determine position

10.10.1.17

MPFSGetSize Function

File

MPFS2.h

284

10.10 MPFS2 Microchip TCP/IP Stack Help

DWORD MPFSGetSize(

);

Returns

The size that was read as a DWORD

Description

Reads the size of a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

MPFS_PTR MPFSGetStartAddr(

Description

the file handle from which to read the metadata

10.10.1.18

MPFSGetStartAddr Function

File

MPFS2.h

);

Returns

The starting address of the file in the MPFS image

Description

Reads the starting address of a file.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

Description

the file handle from which to read the metadata

10.10.1.19

MPFSGetTimestamp Function

File

MPFS2.h

DWORD MPFSGetTimestamp(

);

Returns

The timestamp that was read as a DWORD

Description

Reads the timestamp for the specified file.

MPFS2 Public Members

285

10.10 MPFS2 Microchip TCP/IP Stack Help

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

MPFS_HANDLE MPFSOpen(

Description

the file handle from which to read the metadata

MPFS2 Public Members

10.10.1.20

MPFSOpen Function

File

MPFS2.h

BYTE* cFile

);

Returns

An MPFS_HANDLE ( see page 278) to the opened file if found, or MPFS_INVALID_HANDLE ( see page 278) if the file

could not be found or no free handles exist.

Description

Opens a file in the MPFS2 file system.

Preconditions

MPFSInit ( see page 289) has been called

Parameters

cFile

Description

a null terminated file name to open

10.10.1.21

MPFSOpenID Function

File

MPFS2.h

MPFS_HANDLE MPFSOpenID(

WORD hFatID

);

Returns

An MPFS_HANDLE ( see page 278) to the opened file if found, or MPFS_INVALID_HANDLE ( see page 278) if the file

could not be found or no free handles exist.

Description

Quickly re-opens a file in the MPFS2 file system. Use this function along with MPFSGetID ( see page 283)() to quickly

re-open a file without tying up a permanent MPFSStub.

Preconditions

None

Parameters

hFatID

Description

the ID of a previous opened file in the FAT

286

10.10 MPFS2 Microchip TCP/IP Stack Help MPFS2 Public Members

10.10.1.22

MPFSOpenROM Function

File

MPFS2.h

MPFS_HANDLE MPFSOpenROM(

ROM BYTE* cFile

);

Returns

An MPFS_HANDLE ( see page 278) to the opened file if found, or MPFS_INVALID_HANDLE ( see page 278) if the file

could not be found or no free handles exist.

Description

Opens a file in the MPFS2 file system.

Remarks

This function is aliased to MPFSOpen ( see page 286) on non-PIC18 platforms.

Preconditions

None

Parameters

cFile

Description

a null terminated file name to open

10.10.1.23

MPFSPutArray Function

File

MPFS2.h

WORD MPFSPutArray(

gets stored, MPFSPutEnd ( see page 288) must be called after the last call to MPFSPutArray.

BYTE* cData,

WORD wLen

);

Returns

The number of bytes successfully written.

Description

Writes an array of data to the MPFS image.

Remarks

For EEPROM, the actual write may not initialize until the internal write page is full. To ensure that previously written data

Preconditions

MPFSFormat ( see page 279) was sucessfully called.

Parameters

Description

the file handle for writing

287

10.10 MPFS2 cData wLen

Microchip TCP/IP Stack Help the array of bytes to write how many bytes to write

MPFS2 Stack Members

10.10.1.24

MPFSSeek Function

File

MPFS2.h

BOOL MPFSSeek(

DWORD dwOffset,

MPFS_SEEK_MODE tMode

);

Returns

TRUE - the seek was successful FALSE - either the new location or the handle itself was invalid

Description

Moves the current read pointer to a new location.

Preconditions

The file handle referenced by hMPFS is already open.

Parameters

one of the MPFS_SEEK_MODE ( see page 278) constants

dwOffset tMode

Description

the file handle to seek with offset from the specified position in the specified direction

10.10.1.25

MPFSPutEnd Function

File

MPFS2.h

C void

MPFSPutEnd(

BOOL final

);

Returns

None

Description

Finalizes an MPFS writing operation.

Preconditions

MPFSFormat ( see page 279) and MPFSPutArray ( see page 287) were sucessfully called.

Parameters

final

Description

TRUE if the application is done writing, FALSE if MPFS2 called this function locally.

288

10.10 MPFS2 Microchip TCP/IP Stack Help MPFS2 Internal Members

10.10.2

MPFS2 Stack Members

Functions

Name Description

MPFSInit ( see page 289)

Initializes the MPFS module.

Module

ReadProgramMemory ( see page 293)

Description

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.

10.10.2.1

MPFSInit Function

File

MPFS2.h

C void

MPFSInit();

Returns

None

Description

Sets all MPFS handles to closed, and initializes access to the EEPROM if necessary.

Remarks

This function is called only one during lifetime of the application.

Preconditions

None

Section

Function Definitions

10.10.3

MPFS2 Internal Members

Functions

Name Description

Assembly function to read all three bytes of program memory for 16-bit parts

_LoadFATRecord ( see page 293)

Loads the FAT record for a specified handle.

_Validate ( see page 294)

Validates the MPFS Image

289

10.10 MPFS2 Microchip TCP/IP Stack Help MPFS2 Internal Members

Macros

Module

MAX_FILE_NAME_LEN ( see page 291)

Structures

Name

Description

Supports long file names to 64 characters

Defines the size of a page in EEPROM

Indicates a file has an associated index of dynamic variables

MPFS2_FLAG_ISZIPPED ( see page 292)

Indicates a file is compressed with GZIP compression

MPFSTell ( see page 293)

Alias of MPFSGetPosition ( see page 284)

MPFS_INVALID_FAT ( see page 295)

Indicates an invalid FAT cache

Name

MPFS_STUB ( see page

291)

MPFS_FAT_RECORD ( see page 294)

Description

Stores each file handle's information Handles are free when addr =

MPFS_INVALID ( see page 278)

Stores the data for an MPFS2 FAT record

Types

Name Description

MPFS_PTR ( see page 291) MPFS Pointers are currently DWORDs

Variables

Name

isMPFSLocked ( see page

290)

Description

Allows the MPFS to be locked, preventing access during updates

lastRead ( see page 291)

Track the last read address to prevent unnecessary data overhead to switch locations.

MPFSStubs ( see page 292) Track the MPFS File Handles MPFSStubs[0] is reserved for internal use (FAT

access)

fatCache ( see page 294)

FAT record cache

fatCacheID ( see page 295) ID of currently loaded fatCache ( see page 294)

numFiles ( see page 295)

Number of files in this MPFS image

Description

The following functions and variables are designated as internal to the MPFS2 module.

10.10.3.1

isMPFSLocked Variable

File

MPFS2.c

BOOL isMPFSLocked;

Description

Allows the MPFS to be locked, preventing access during updates

290

10.10 MPFS2 Microchip TCP/IP Stack Help

10.10.3.2

lastRead Variable

File

MPFS2.c

MPFS_PTR lastRead;

Description

Track the last read address to prevent unnecessary data overhead to switch locations.

10.10.3.3

MAX_FILE_NAME_LEN Macro

File

MPFS2.c

#define

MAX_FILE_NAME_LEN (64u)

Description

Supports long file names to 64 characters

10.10.3.4

MPFS_PTR Type

File

MPFS2.h

C typedef

DWORD MPFS_PTR;

Description

MPFS Pointers are currently DWORDs

10.10.3.5

MPFS_STUB Structure

File

MPFS2.h

C typedef struct

{

MPFS_PTR addr;

DWORD bytesRem;

WORD fatID;

} MPFS_STUB;

Members

MPFS_PTR addr;

DWORD bytesRem;

WORD fatID;

Description

Current address in the file system

How many bytes remain in this file

ID of which file in the FAT was accessed

MPFS2 Internal Members

291

10.10 MPFS2 Microchip TCP/IP Stack Help MPFS2 Internal Members

Description

Stores each file handle's information Handles are free when addr = MPFS_INVALID ( see page 278)

10.10.3.6

MPFS_WRITE_PAGE_SIZE Macro

File

MPFS2.h

#define

MPFS_WRITE_PAGE_SIZE (64u)

// Defines the size of a page in EEPROM

Description

Defines the size of a page in EEPROM

10.10.3.7

MPFS2_FLAG_HASINDEX Macro

File

MPFS2.h

#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

10.10.3.8

MPFS2_FLAG_ISZIPPED Macro

File

MPFS2.h

#define

MPFS2_FLAG_ISZIPPED ((WORD)0x0001)

// Indicates a file is compressed with GZIP compression

Description

Indicates a file is compressed with GZIP compression

10.10.3.9

MPFSStubs Variable

File

MPFS2.c

MPFS_STUB MPFSStubs[MAX_MPFS_HANDLES+1];

Description

Track the MPFS File Handles MPFSStubs[0] is reserved for internal use (FAT access)

292

10.10 MPFS2 Microchip TCP/IP Stack Help

10.10.3.10

MPFSTell Macro

File

MPFS2.h

#define

MPFSTell(a) MPFSGetPosition(a)

Description

Alias of MPFSGetPosition ( see page 284)

10.10.3.11

ReadProgramMemory Function

File

MPFS2.h

DWORD ReadProgramMemory(

DWORD address

);

Description

Assembly function to read all three bytes of program memory for 16-bit parts

10.10.3.12

_LoadFATRecord Function

File

MPFS2.c

C static void

_LoadFATRecord(

WORD fatID

);

Returns

None

Description

Loads the FAT record for a specified handle.

Remarks

The FAT record will be stored in fatCache ( see page 294).

Preconditions

None

Parameters

fatID

Description

the ID of the file whose FAT is to be loaded

MPFS2 Internal Members

293

10.10 MPFS2 Microchip TCP/IP Stack Help MPFS2 Internal Members

10.10.3.13

_Validate Function

File

MPFS2.c

C static void

_Validate();

Returns

None

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

10.10.3.14

MPFS_FAT_RECORD Structure

File

MPFS2.h

C typedef struct

{

DWORD string;

DWORD data;

DWORD len;

DWORD timestamp;

DWORD microtime;

WORD flags;

} MPFS_FAT_RECORD;

Members

DWORD string;

DWORD data;

DWORD len;

DWORD timestamp;

DWORD microtime;

WORD flags;

Description

Stores the data for an MPFS2 FAT record

Description

Pointer to the file name

Address ( see page 152) of the file data

Length of file data

Timestamp of file

Microtime stamp of file

Flags for this file

10.10.3.15

fatCache Variable

File

MPFS2.c

MPFS_FAT_RECORD fatCache;

294

10.11 NBNS

Description

FAT record cache

Microchip TCP/IP Stack Help

10.10.3.16

fatCacheID Variable

File

MPFS2.c

WORD fatCacheID;

Description

ID of currently loaded fatCache ( see page 294)

10.10.3.17

numFiles Variable

File

MPFS2.c

WORD numFiles;

Description

Number of files in this MPFS image

10.10.3.18

MPFS_INVALID_FAT Macro

File

MPFS2.h

#define

MPFS_INVALID_FAT (0xffffu)

// Indicates an invalid FAT cache

Description

Indicates an invalid FAT cache

NBNS Stack Members

10.11

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.

295

10.11 NBNS Microchip TCP/IP Stack Help NBNS Stack Members

10.11.1

NBNS Stack Members

Functions

Name

NBNSGetName ( see page

296)

Description

Reads the NetBIOS name from a UDP socket and copies it into a user-specified buffer.

NBNSPutName ( see page

297)

Transmits the NetBIOS name across an open UDP socket.

NBNSTask ( see page 297) Sends responses to NetBIOS name requests

Macros

Name

NBNS_PORT ( see page

298)

Module

NBNS ( see page 295)

Description

NetBIOS Name Service port

Structures

Name

NBNS_HEADER ( see page 298)

_NBNS_HEADER ( see page 298)

Description

NBNS Header structure

Description

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.

10.11.1.1

NBNSGetName Function

File

NBNS.c

C static void

NBNSGetName(

BYTE * String

);

Side Effects

None

Returns

None

Description

Reads the NetBIOS name from a UDP socket and copies it into a user-specified buffer.

Remarks

None

Preconditions

None

296

10.11 NBNS

Parameters

String

Microchip TCP/IP Stack Help NBNS Stack Members

Description

Pointer to an array into which a received NetBIOS name should be copied.

10.11.1.2

NBNSPutName Function

File

NBNS.c

C static void

NBNSPutName(

BYTE * String

);

Side Effects

None

Returns

None

Description

Transmits the NetBIOS name across an open UDP socket.

Remarks

None

Preconditions

None

Parameters

String

Description

The name to transmit

10.11.1.3

NBNSTask Function

File

NBNS.h

C void

NBNSTask();

Side Effects

None

Returns

None

Description

Sends responses to NetBIOS name requests

Remarks

None

Preconditions

None

297

Performance Test Stack Members 10.12 Performance Tests Microchip TCP/IP Stack Help

10.11.1.4

NBNS_HEADER Structure

File

NBNS.c

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

10.11.1.5

NBNS_PORT Macro

File

NBNS.c

#define

NBNS_PORT (137u)

Description

NetBIOS Name Service port

10.12

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 ( see page 299),

TCPTXPerformanceTask ( see page 301), and TCPRXPerformanceTask ( see page 300).

10.12.1

Performance Test Stack Members

Functions

Name Description

TCPPerformanceTask ( see page 299)

Tests the performance of the TCP module.

UDPPerformanceTask ( see page 299)

Tests the transmit performance of the UDP module.

298

10.12 Performance Tests Microchip TCP/IP Stack Help Performance Test Internal Members

Module

Performance Tests ( see page 298)

Description

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.

10.12.1.1

TCPPerformanceTask Function

File

TCPPerformanceTest.h

C void

TCPPerformanceTask();

Returns

None

Description

This function calls both TCPTXPerformanceTask (

see page 301) and TCPRXPerformanceTask ( see page 300) to

perform the performance task functions. Refer to the documentation for each of those functions for details.

Preconditions

TCP is initialized.

10.12.1.2

UDPPerformanceTask Function

File

UDPPerformanceTest.h

C void

UDPPerformanceTask();

Returns

None

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.

299

10.12 Performance Tests Microchip TCP/IP Stack Help Performance Test Internal Members

10.12.2

Performance Test Internal Members

Functions

Name

TCPRXPerformanceTask ( see page 300)

TCPTXPerformanceTask ( see page 301)

Description

Tests the receive performance of the TCP module.

Tests the transmit performance of the TCP module.

Macros

Name

PERFORMANCE_PORT ( see page 301)

Description

Which UDP port to broadcast from for the UDP tests

RX_PERFORMANCE_PORT

( see page 301)

The TCP port to listen ( see page 180) on for TCP receive tests

TX_PERFORMANCE_PORT

( see page 302)

The TCP port to listen ( see page 180) on for TCP transmit tests

Module

Performance Tests ( see page 298)

Description

The following functions and variables are designated as internal to the module.

10.12.2.1

TCPRXPerformanceTask Function

File

TCPPerformanceTest.c

C void

TCPRXPerformanceTask();

Returns

None

Description

This function tests the receive performance of the TCP module. To use, open a telnet connection to the device on

RX_PERFORMANCE_PORT ( see page 301) (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.

Preconditions

TCP is initialized.

300

10.12 Performance Tests Microchip TCP/IP Stack Help Performance Test Internal Members

10.12.2.2

TCPTXPerformanceTask Function

File

TCPPerformanceTest.c

C void

TCPTXPerformanceTask();

Returns

None

Description

This function tests the transmit performance of the TCP module. To use, open a telnet connection to the device on

TX_PERFORMANCE_PORT ( see page 302) (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.

Preconditions

TCP is initialized.

10.12.2.3

PERFORMANCE_PORT Macro

File

UDPPerformanceTest.c

#define

PERFORMANCE_PORT 9

Description

Which UDP port to broadcast from for the UDP tests

10.12.2.4

RX_PERFORMANCE_PORT Macro

File

TCPPerformanceTest.c

#define

RX_PERFORMANCE_PORT 9763

Description

The TCP port to listen ( see page 180) on for TCP receive tests

301

SMTP Client Examples 10.13 SMTP Client Microchip TCP/IP Stack Help

10.12.2.5

TX_PERFORMANCE_PORT Macro

File

TCPPerformanceTest.c

#define

TX_PERFORMANCE_PORT 9762

Description

The TCP port to listen ( see page 180) on for TCP transmit tests

10.13

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.

10.13.1

SMTP Client Examples

Module

The SMTP client API is simplified when messages can be buffered entirely in RAM. The

Description

The following two examples demonstrate the use of the SMTP client in different scenarios. The first, and simpler example, sends a short message whose contents are all located in RAM at once.

The second example is more involved and demonstrates generating a message on the fly in the case where the entire message cannot fit into RAM at once. In this case, the message is started by the stack, but the delivery of the contents happens in pieces and is handled by the application.

10.13.1.1

SMTP Client Short Message Example

SMTPDemo ( see page 101)

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:

302

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Examples

First, call SMTPBeginUsage ( see page 308) to verify that the SMTP client is available and to begin a new message. If

FALSE is returned, the SMTP client is busy and the application must return to the main loop to allow StackTask to execute again.

Next, set the local relay server to use as SMTPClient.Server

. If the local relay server requires a user name and password, set

SMTPClient.Username

and

SMTPClient.Password

to the appropriate credentials.

If server parameters are not set, the stack will attempt to deliver the message directly to its destination host. This will likely fail due to spam prevention measures put in place by most ISPs and network administrators.

Continue on to set the header strings as necessary for the message. This includes the subject line, from address, and any recipients you need to add. Finally, set

SMTPClient.Body

to the message to be sent.

At this point, verify that

SMTPClient.ROMPointers

is correctly configured for any strings that are stored in program

memory. Once the message is ready to send, call SMTPSendMail ( see page 314) to instruct the SMTP client to begin

transmission.

The application must now call SMTPIsBusy ( see page 310) until it returns

FALSE

. Each time

TRUE

is returned, return to the main loop and wait for StackTask to execute again. This allows the SMTP server to continue its work in a cooperative multitasking manner. Once FALSE

is returned, call SMTPEndUsage ( see page 309) to release the SMTP client. Check the

return value of this function to determine if the message was successfully sent.

The example in MainDemo.c

needs minor modifications to use your e-mail address. The Server and To fields must be set in

SMTPDemo ( see page 101)

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.

10.13.1.2

SMTP Client Long Message Example

The SMTP client API is capable of sending messages that do not fit entirely in RAM. To do so, the application must manage

its output state and only write as many bytes as are available in the buffer at a time. The second

SMTPDemo ( see page

101)

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:

303

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Examples

The first stage is largely similar to the first few steps in sending a short message. First, call SMTPBeginUsage ( see page

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

Continue on to set the header strings as necessary for the message. This includes the subject line, from address, and any recipients you need to add.

The next portion of the process differs. Ensure that

SMTPClient.Body

remains set to its default (NULL). At this point, call

SMTPSendMail ( see page 314) 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 ( see page 310) to verify that the connection to the remote server is active and has not been lost. If the call succeeds, call SMTPIsPutReady ( see page 310) to determine

how many bytes are available in the TX buffer. If no bytes are available, return to the main loop so that StackTask can transmit the data to the remote node and free up the buffer.

If space is available, any combination of the SMTPPut ( see page 311), SMTPPutArray ( see page 311),

SMTPPutROMArray (

see page 312), SMTPPutString ( see page 313), and SMTPPutROMString ( see page 313)

functions may be called to transmit the message. These functions return the number of bytes successfully written. Use this

value, along with the value originally returned from SMTPIsPutReady ( see page 310) to track how much free space

304

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Public Members

remains in the TX buffer. Once the buffer is depleted, call SMTPFlush ( see page 309) to force the data written to be sent.

The SMTP client module can accept ( see page 174) as much data as the TCP TX FIFO can hold. This is determined by

the socket initializer for TCP_PURPOSE_DEFAULT type sockets in

TCPIPConfig.h

, which defaults to 200 bytes.

If the TX buffer is exhausted before the message is complete, return to the main loop so that StackTask may transmit the data to the remote node and free up the buffer. Upon return, go to the beginning of the second stage to transmit the next portion of the message.

Once the message is complete, the application will move to the third stage. Call SMTPPutDone ( see page 312) to inform

the SMTP client that no more data remains. Then call SMTPIsBusy ( see page 310) repeatedly. Each time

TRUE is returned, return to the main loop and wait for StackTask to execute again. Once

FALSE

is returned, the message

transmission has completed and the application must call SMTPEndUsage ( see page 309) 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

fields in

SMTPDemo ( see page 101)

, and ensure that these fields are being properly assigned to SMTPClient ( see page

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

10.13.2

SMTP Client Public Members

Functions

Name

SMTPBeginUsage ( see page 308)

Description

Requests control of the SMTP client module.

SMTPEndUsage ( see page 309)

Releases control of the SMTP client module.

SMTPFlush ( see page 309) Flushes the SMTP socket and forces all data to be sent.

Determines if the SMTP client is busy.

SMTPIsBusy ( see page

310)

SMTPIsPutReady ( see page 310)

Determines how much data can be written to the SMTP client.

SMTPPut ( see page 311)

Writes a single byte to the SMTP client.

SMTPPutArray ( see page

311)

Writes a series of bytes to the SMTP client.

Indicates that the on-the-fly message is complete.

SMTPPutDone ( see page

312)

SMTPPutROMArray ( see page 312)

SMTPPutROMString ( see page 313)

Writes a series of bytes from ROM to the SMTP client.

Writes a string from ROM to the SMTP client.

SMTPPutString ( see page

313)

SMTPSendMail ( see page

314)

Writes a string to the SMTP client.

Initializes the message sending process.

Macros

Name

SMTP_CONNECT_ERROR

( see page 306)

Description

Connection to SMTP server failed

305

10.13 SMTP Client Microchip TCP/IP Stack Help

SMTP_RESOLVE_ERROR

( see page 308)

SMTP_SUCCESS ( see page 308)

Module

SMTP_POINTERS ( see page 306)

DNS lookup for SMTP server failed

Message was successfully sent

Structures

Name

Description

Configures the SMTP client to send a message

Variables

Name

SMTPClient ( see page 309)

Description

The following functions and variables are available to the stack application.

SMTP Client Public Members

10.13.2.1

SMTP_CONNECT_ERROR Macro

File

SMTP.h

#define

SMTP_CONNECT_ERROR (0x8001u)

// Connection to SMTP server failed

Description

Connection to SMTP server failed

10.13.2.2

SMTP_POINTERS Structure

File

SMTP.h

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;

306

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Public Members

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 ( see page 309).[field name].szRAM

to use a string stored in RAM, or

SMTPClient ( see page 309).[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.

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"

<[email protected]>

Parameters

Server

Username

Password

BCC

From

Subject

Description

the SMTP server to relay the message through the user name to use when logging into the SMTP server, if any is required the password to supply when logging in, if any is required the destination address for this message. May be a comma-separated list of addresss, and/or formatted.

The CC addresses for this message, if any. May be a comma-separated list of addresss, and/or formatted.

The BCC addresses for this message, if any. May be a comma-separated list of addresss, and/or formatted.

The From address for this message. May be formatted.

The Subject header for this message.

307

10.13 SMTP Client

OtherHeaders

Body

ROMPointers

UseSSL

ServerPort ( see page 103)

Microchip TCP/IP Stack Help SMTP Client Public Members

Any additional headers for this message. Each additional header, including the last one, must be terminated with a CRLF pair.

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.

Indicates which parameters to read from ROM instead of RAM.

When STACK_USE_SSL_CLIENT is enabled, this flag causes the SMTP client to make an SSL connection to the server.

(WORD value) Indicates the port on which to connect ( see page 176) to the

remote SMTP server.

10.13.2.3

SMTP_RESOLVE_ERROR Macro

File

SMTP.h

#define

SMTP_RESOLVE_ERROR (0x8000u)

// DNS lookup for SMTP server failed

Description

DNS lookup for SMTP server failed

10.13.2.4

SMTP_SUCCESS Macro

File

SMTP.h

#define

SMTP_SUCCESS (0x0000u)

// Message was successfully sent

Description

Message was successfully sent

10.13.2.5

SMTPBeginUsage Function

File

SMTP.h

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 ( see page 309) 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

TRUE

Description

The application has successfully obtained control of the module

308

10.13 SMTP Client

FALSE

Section

SMTP Function Prototypes

Microchip TCP/IP Stack Help SMTP Client Public Members

The SMTP module is in use by another application. Call SMTPBeginUsage again later, after returning to the main program loop

10.13.2.6

SMTPClient Variable

File

SMTP.c

SMTP_POINTERS SMTPClient;

Section

SMTP Client Public Variables

************************************************************************

The global set of SMTP_POINTERS.

Set these parameters after calling SMTPBeginUsage successfully.

10.13.2.7

SMTPEndUsage Function

File

SMTP.h

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 ( see page 308), and frees the SMTP client to be used by another application.

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

Return Values

SMTP_SUCCESS ( see page 308)

SMTP_RESOLVE_ERROR ( see page

308)

SMTP_CONNECT_ERROR ( see page

306)

1-199 and 300-399

Description

A message was successfully sent

The SMTP server could not be resolved

The connection to the SMTP server failed or was prematurely terminated

The last SMTP server response code

10.13.2.8

SMTPFlush Function

File

SMTP.h

309

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Public Members

C void

SMTPFlush();

Returns

None

Description

Flushes the SMTP socket and forces all data to be sent.

Remarks

This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is,

SMTPSendMail ( see page 314) was called with SMTPClient.Body set to NULL.)

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

10.13.2.9

SMTPIsBusy Function

File

SMTP.h

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 (

see page 314), SMTPPutDone ( see page 312) to determine if the stack has finished

performing its internal tasks. It should also be called prior to any call to SMTPIsPutReady ( see page 310) to verify that the

SMTP client has not prematurely disconnected. When this function returns FALSE, the next call should be to

SMTPEndUsage ( see page 309) to release the module and obtain the status code for the operation.

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

Return Values

TRUE

FALSE

Description

The SMTP Client is busy with internal tasks or sending an on-the-fly message.

The SMTP Client is terminated and is ready to be released.

10.13.2.10

SMTPIsPutReady Function

File

SMTP.h

WORD SMTPIsPutReady();

Returns

The number of free bytes the SMTP TX FIFO.

Description

Use this function to determine how much data can be written to the SMTP client when generating an on-the-fly message.

310

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Public Members

Remarks

This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is,

SMTPSendMail ( see page 314) was called with SMTPClient.Body set to NULL.)

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call, and an on-the-fly message is being generated. This

requires that SMTPSendMail ( see page 314) was called with SMTPClient.Body set to NULL.

10.13.2.11

SMTPPut Function

File

SMTP.h

BOOL SMTPPut(

BYTE c

);

Description

Writes a single byte to the SMTP client.

Remarks

This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is,

SMTPSendMail ( see page 314) was called with SMTPClient.Body set to NULL.)

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

Parameters

Return Values

TRUE

FALSE

Description

The byte to be written

Description

The byte was successfully written

The byte was not written, most likely because the buffer was full

10.13.2.12

SMTPPutArray Function

File

SMTP.h

WORD SMTPPutArray(

BYTE* Data,

WORD Len

);

Returns

The number of bytes written. If less than Len, then the TX FIFO became full before all bytes could be written.

Description

Writes a series of bytes to the SMTP client.

311

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Public Members

Remarks

This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is,

SMTPSendMail ( see page 314) was called with SMTPClient.Body set to NULL.)

Internal

SMTPPut ( see page 311) must be used instead of TCPPutArray ( see page 550) because "rn." must be transparently

replaced by "rn..".

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

Parameters

Data

Len

Description

The data to be written

How many bytes should be written

10.13.2.13

SMTPPutDone Function

File

SMTP.h

C void

SMTPPutDone();

Returns

None

Description

Indicates that the on-the-fly message is complete.

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call, and the SMTP client is generated an on-the-fly

message. (That is, SMTPSendMail ( see page 314) was called with SMTPClient.Body set to NULL.)

10.13.2.14

SMTPPutROMArray Function

File

SMTP.h

WORD SMTPPutROMArray(

ROM BYTE* Data,

WORD Len

);

Returns

The number of bytes written. If less than Len, then the TX FIFO became full before all bytes could be written.

Description

Writes a series of bytes from ROM to the SMTP client.

Remarks

This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is,

SMTPSendMail ( see page 314) was called with SMTPClient.Body set to NULL.)

312

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Public Members

This function is aliased to SMTPPutArray ( see page 311) on non-PIC18 platforms.

Internal

SMTPPut ( see page 311) must be used instead of TCPPutArray ( see page 550) because "rn." must be transparently

replaced by "rn..".

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

Parameters

Data

Len

Description

The data to be written

How many bytes should be written

10.13.2.15

SMTPPutROMString Function

File

SMTP.h

WORD SMTPPutROMString(

ROM BYTE* Data

);

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.

Description

Writes a string from ROM to the SMTP client.

Remarks

This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is,

SMTPSendMail ( see page 314) was called with SMTPClient.Body set to NULL.)

This function is aliased to SMTPPutString ( see page 313) on non-PIC18 platforms.

Internal

SMTPPut ( see page 311) must be used instead of TCPPutString ( see page 552) because "rn." must be transparently

replaced by "rn..".

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

Parameters

Data

Description

The data to be written

10.13.2.16

SMTPPutString Function

File

SMTP.h

WORD SMTPPutString(

BYTE* Data

);

313

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Stack Members

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.

Description

Writes a string to the SMTP client.

Remarks

This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is,

SMTPSendMail ( see page 314) was called with SMTPClient.Body set to NULL.)

Internal

SMTPPut ( see page 311) must be used instead of TCPPutString ( see page 552) because "rn." must be transparently

replaced by "rn..".

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

Parameters

Data

Description

The data to be written

10.13.2.17

SMTPSendMail Function

File

SMTP.h

C void

SMTPSendMail();

Returns

None

Description

This function starts the state machine that performs the actual transmission of the message. Call this function after all the

fields in SMTPClient ( see page 309) have been set.

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

10.13.3

SMTP Client Stack Members

Functions

Name Description

SMTPTask ( see page 315) Performs any pending SMTP client tasks

Module

FindEmailAddress ( see page 316)

Description

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.

314

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Internal Members

10.13.3.1

SMTPTask Function

File

SMTP.h

C void

SMTPTask();

Returns

None

Description

This function handles periodic tasks associated with the SMTP client, such as processing initial connections and command sequences.

Remarks

Preconditions

None

10.13.4

SMTP Client Internal Members

Functions

Name

FindROMEmailAddress ( see page 317)

Description

Searches a string for an e-mail address.

Searches a ROM string for an e-mail address.

Macros

Name

SMTP_PORT ( see page 319)

Description

Default port to use when unspecified

Module

SMTP_SERVER_REPLY_TIMEOUT

Variables

( see page 319)

How long to wait before assuming the connection has been dropped

(default 8 seconds)

Name Description

CRPeriod ( see page 316)

State machine for the CR LF Period replacement Used by SMTPPut ( see page 311) to transparently replace "rn." with "rn.."

MySocket ( see page 317)

Socket currently in use by the SMTP client

State machine for writing the SMTP message headers

PutHeadersState ( see page 317)

ResponseCode ( see page

318)

Response code from server when an error exists

RXParserState ( see page

318)

State machine for parsing incoming responses

315

10.13 SMTP Client Microchip TCP/IP Stack Help SMTP Client Internal Members

SMTPFlags ( see page 319) Internal flags used by the SMTP Client

SMTPServer ( see page

319)

IP address of the remote SMTP server

SMTPState ( see page 320) Message state machine for the SMTP Client

TransportState ( see page

321)

State of the transport for the SMTP Client

Description

The following functions and variables are designated for internal use by the SMTP Client module.

10.13.4.1

CRPeriod Variable

File

SMTP.c

C union

{

BYTE * Pos;

enum

{

CR_PERIOD_SEEK_CR = 0,

CR_PERIOD_SEEK_LF,

CR_PERIOD_SEEK_PERIOD,

CR_PERIOD_NEED_INSERTION

} State;

} CRPeriod;

Members

CR_PERIOD_SEEK_CR = 0

CR_PERIOD_SEEK_LF

CR_PERIOD_SEEK_PERIOD

CR_PERIOD_NEED_INSERTION

Description

Idle state, waiting for 'r r" has been written, so check next byte for 'n rn" has been written, so check next byte for '.

"rn." has been written, so an additional '.' must be written before the next byte.

Description

State machine for the CR LF Period replacement Used by SMTPPut ( see page 311) to transparently replace "rn." with

"rn.."

10.13.4.2

FindEmailAddress Function

File

SMTP.c

C static

BYTE * FindEmailAddress(

BYTE * str,

WORD * wLen

);

Returns

A pointer to the e-mail address

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.

316

10.13 SMTP Client Microchip TCP/IP Stack Help

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

Parameters

str wLen

Section

SMTP Client Internal Function Prototypes

Description

The string in which to search for an e-mail address the length of str

SMTP Client Internal Members

10.13.4.3

FindROMEmailAddress Function

File

SMTP.c

C static

ROM BYTE * FindROMEmailAddress(

ROM BYTE * str,

WORD * wLen

);

Returns

A pointer to the e-mail address

Description

Preconditions

SMTPBeginUsage ( see page 308) returned TRUE on a previous call.

Parameters

str wLen

Description

The ROM string in which to search for an e-mail address the length of str

10.13.4.4

MySocket Variable

File

SMTP.c

TCP_SOCKET MySocket = INVALID_SOCKET;

Description

Socket currently in use by the SMTP client

10.13.4.5

PutHeadersState Variable

File

SMTP.c

317

10.13 SMTP Client Microchip TCP/IP Stack Help

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;

Members

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

Description

Preparing to send From header

Sending From header

Preparing to send To header

Sending To header

Preparing to send CC header

Sending CC header

Preparing to send Subject header

Sending Subject header

Preparing to send additional headers

Sending additional headers

Done writing all headers

Description

State machine for writing the SMTP message headers

10.13.4.6

ResponseCode Variable

File

SMTP.c

WORD ResponseCode;

Description

Response code from server when an error exists

10.13.4.7

RXParserState Variable

File

SMTP.c

C enum

{

RX_BYTE_0 = 0,

RX_BYTE_1,

RX_BYTE_2,

RX_BYTE_3,

RX_SEEK_CR,

RX_SEEK_LF

SMTP Client Internal Members

318

10.13 SMTP Client

} RXParserState;

Description

State machine for parsing incoming responses

Microchip TCP/IP Stack Help SMTP Client Internal Members

10.13.4.8

SMTP_PORT Macro

File

SMTP.c

#define

SMTP_PORT 25

// Default port to use when unspecified

Description

Default port to use when unspecified

10.13.4.9

SMTP_SERVER_REPLY_TIMEOUT Macro

File

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

10.13.4.10

SMTPFlags Variable

File

SMTP.c

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

10.13.4.11

SMTPServer Variable

File

SMTP.c

319

10.13 SMTP Client

IP_ADDR SMTPServer;

Description

IP address of the remote SMTP server

Microchip TCP/IP Stack Help SMTP Client Internal Members

10.13.4.12

SMTPState Variable

File

SMTP.c

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;

Members

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

Description

Idle start state for SMTP client (application is preparing message)

HELO is being sent to server

Received an ACK for the HELO

Requesting to log in

Sending user name

User name accepted

Sending password

Password was accepted

Sending inital MAIL FROM command

MAIL FROM was accepted

Preparing to send RCPT TO

320

10.14 Reboot Microchip TCP/IP Stack Help

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

Description

Message state machine for the SMTP Client

Sending RCPT TO command

RCPT TO was accepted

Done sending RCPT TO commands

Preparing to send RCPT TO CC commands

Sending RCPT TO CC commands

RCPT TO CC was accepted

Done sending RCPT TO CC

Preparing to send RCPT TO BCC commands

Sending RCPT TO BCC commands

RCPT TO BCC was accepted

Done sending RCPT TO BCC

Sending DATA command

DATA command accpted

Sending message headers

Preparing for message body

Sending message body

Message body accepted

Sending QUIT command

QUIT accepted, connection closing

10.13.4.13

TransportState Variable

File

SMTP.c

C enum

{

TRANSPORT_HOME = 0,

TRANSPORT_BEGIN,

TRANSPORT_NAME_RESOLVE,

TRANSPORT_OBTAIN_SOCKET,

TRANSPORT_SECURING_SOCKET,

TRANSPORT_SOCKET_OBTAINED,

TRANSPORT_CLOSE

} TransportState;

Members

TRANSPORT_HOME = 0

TRANSPORT_BEGIN

TRANSPORT_NAME_RESOLVE

TRANSPORT_OBTAIN_SOCKET

TRANSPORT_SECURING_SOCKET

TRANSPORT_SOCKET_OBTAINED

TRANSPORT_CLOSE

Description

State of the transport for the SMTP Client

Description

Idle state

Preparing to make connection

Resolving the SMTP server address

Obtaining a socket for the SMTP connection

Securing the socket for the SMTP over SSL connection

SMTP connection successful

STMP socket is closed

321

10.14 Reboot Microchip TCP/IP Stack Help Reboot Stack Members

10.14

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

10.14.1

Reboot Stack Members

Functions

Name Description

RebootTask ( see page 322) Checks for incomming traffic on port 69. Resets the PIC if a 'R' is received.

Macros

Name Description

REBOOT_PORT ( see page 323) UDP TFTP port

REBOOT_SAME_SUBNET_ONLY

( see page 323)

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 ( see page 322)

Description

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.

10.14.1.1

RebootTask Function

File

Reboot.h

C void

RebootTask();

Side Effects

None

Returns

None

Description

Checks for incomming traffic on port 69. Resets the PIC if a 'R' is received.

322

10.15 SNMP Microchip TCP/IP Stack Help

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.

Preconditions

Stack is initialized()

10.14.1.2

REBOOT_PORT Macro

File

Reboot.c

#define

REBOOT_PORT 69

// UDP TFTP port

Description

UDP TFTP port

10.14.1.3

REBOOT_SAME_SUBNET_ONLY Macro

File

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

10.15

SNMP

Files

Name

Description

• Simple Network Management Protocol (SNMP) Version 3 Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMPv3 API for doing stuff

• -Reference: RFCs 3410, 3411, 3412, 3413, 3414

323

10.15 SNMP

_IsSNMPv3ValidStructure ( see page 379)

Microchip TCP/IP Stack Help

• Simple Network Management Protocol (SNMP) Version 3 Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMPv3 API for doing stuff

• -Reference: RFCs 3410, 3411, 3412, 3413, 3414

• Simple Network Management Protocol (SNMP) Version 3 Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMPv3 API for doing stuff

• -Reference: RFCs 3410, 3411, 3412, 3413, 3414

• Simple Network Management Protocol (SNMP) Version 1 Agent

• Simple Network Management Protocol (SNMP) Version 2 community based Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMP API for doing stuff

• -Reference: RFC 1157 (for SNMP V1)

• RFC 3416 (for SNMPv2C)

• SNMP Defs for Microchip TCP/IP Stack

Functions

Name

_Snmpv3IsValidAuthStructure ( see page 379)

_Snmpv3IsValidInt ( see page 380)

FindOIDsFromSnmpV3Request ( see page 381) getSnmpV2GenTrapOid ( see page 381)

IsSnmpV3ASNNull ( see page 382)

IsSnmpv3ValidOID ( see page 382)

IsSNMPv3ValidStructure ( see page 383)

ProcessGetBulkVar ( see page 383)

ProcessGetNextVar ( see page 384)

Description

Decode variable length structure.

Verifies variable datatype as INT and retrieves its value.

Finds number of varbinds in the varbind list received in a SNMPv3 pdu.

Resolves generic trap code to generic trap OID.

Verifies the value type as ASN_NULL ( see page 349).

Populates OID type, length and oid string from the received pdu.

Decode variable length structure.

This routine process the SNMPv2c Get Bulk Request.

Retrieves next node from the MIB database.

324

10.15 SNMP Microchip TCP/IP Stack Help

ProcessGetVar ( see page 385)

ProcessSnmpv3MsgData ( see page 385)

SNMPGetExactIndex ( see page 386)

SNMPIdRecrdValidation ( see page 386)

SNMPIsValidSetLen ( see page 387)

Processes snmp Get request pdu.

This routine processes the snmpv3 request and parallely creates the response pdu.

To search for exact index node in case of a Sequence variable.

Used to Restrict the access dynamic and non dynamic

OID string for A perticular SNMP Version.

Validates the set variable data length to data type.

Snmpv3AESDecryptRxedScopedPdu ( see page

388)

Snmpv3AESEncryptResponseScopedPdu ( see page 388)

Incoming SNMPv3 scoped PDU decryption using AES decryption protocol.

outGoing SNMPv3 scoped PDU Encryption using AES encryption protocol.

Snmpv3AuthenticateRxedPduForDataIntegrity ( see page 389)

Authenticate an incoming SNMPV3 USM PDU using

MD5 or SHA

Snmpv3AuthenticateTxPduForDataIntegrity ( see page 389)

Authenticate to an outgoing SNMPV3 USM PDU using

MD5 or SHA

Snmpv3AuthKeyZeroing2HmacBufLen64 ( see page 390)

Snmpv3BufferPut ( see page 390)

Pad zero to the authentication key localized buffer.

Copies BYTE data to dynamically allocated memory buffer.

Snmpv3CmprTrapSecNameAndSecLvlWithUSMDb

Snmpv3ComputeHMACIpadOpadForAuthLoclzedKey

Routine to find the index of the user name in the user data base table.

Snmpv3ComputeHmacMD5Digest ( see page 392)

Compute HMAC inner and outer pad for authorization localized key.

Compute HMAC - MD5 authentication code

Snmpv3ComputeHmacShaDigest ( see page 393)

Compute HMAC - SHA authentication code

Snmpv3ComputeMd5HmacCode ( see page 393)

Compute HMAC - MD5 authentication code

Snmpv3ComputeShaHmacCode ( see page 394)

Snmpv3FormulateEngineID ( see page 394)

Snmpv3FreeDynAllocMem ( see page 395)

Snmpv3GetAuthEngineTime ( see page 395)

Compute HMAC - SHA authentication code

Formulates the snmpEngineID ( see page 433) for the

SNMPV3 engine.

Allocated dynamic memory freeing is done by this routine.

Updates the snmp engine time variable

'snmpEngineTime ( see page 434)' for the SNMPV3

engine.

Snmpv3GetBufferData ( see page 396)

Snmpv3GetSecurityLevel ( see page 396)

Snmpv3GetTrapSecurityLevel ( see page 397)

Reads BYTE data from dynamically allocated memory buffer.

Get Security level from authentication and Privacy type.

Routine to find the report, auth and privacy flags settings in the TRAP.

Snmpv3Init ( see page 397)

Snmpv3InitializeUserDataBase ( see page 398)

Snmpv3IsValidAuthStructure ( see page 398)

Snmpv3IsValidInt ( see page 399)

Snmpv3MsgProcessingModelProcessPDU ( see page 399)

SNMPv3 initialization.

Intialize default SNMPv3 global user database.

Decode variable length structure.

Verifies variable datatype as INT and retrieves its value.

This routine collects or populates the message processing model infomation from the received

SNMPv3 request PDU or to the response PDU respectively.

Snmpv3Notify ( see page 400)

Creates and Sends SNMPv3 TRAP pdu.

Snmpv3Pswd2LocalizedAuthKeyMD5Hashing ( see page 400)

Convert MD5 Auth password to the localized Key using

SNMPEngineID.

Snmpv3Pswd2LocalizedAuthKeySHAHashing ( see page 401)

Convert SHA Auth password to the localized Key using

SNMPEngineID.

325

10.15 SNMP Microchip TCP/IP Stack Help

Snmpv3ReportPdu ( see page 401)

Snmpv3ScopedPduProcessing ( see page 402)

Snmpv3SetErrorStatus ( see page 402)

Snmpv3TrapScopedpdu ( see page 403)

Snmpv3UserSecurityModelProcessPDU ( see page

404)

Constructs the report pdu infomration for the Report

Pdu.

This routine collects the scoped pdu header information from the received SNMPv3 request PDU or populates to the response PDU respectively.

Set snmpv3 error status in the response pdu.

TRAP PDU scoped pdu header construction.

This routine collects or populates the security model parametrs infomation from the received SNMPv3 request PDU or to the response PDU respectively.

AES Encryption and decryption init vector.(RFC 3826 )

Snmpv3UsmAesEncryptDecryptInitVector ( see page 404)

Snmpv3UsmOutMsgAuthenticationParam ( see page 405)

Snmpv3USMOutMsgPrivParam ( see page 405)

Snmpv3UsmSnmpEngnAuthPrivPswdLocalization ( see page 405)

Snmpv3ValidateEngineId ( see page 406)

Snmpv3ValidateSecNameAndSecLvl ( see page

406)

Snmpv3ValidateSecurityName ( see page 407)

Both MD5 and SHA1 is used for the outgoing message authentication.

SNMP USM out message uses Privacy protocol (RFC

3826 )

Convert Auth and Priv password to the localized Key using SNMPEngineID.

Validate engine ID.

Vaidate security name with Security level.

Validate SNMPV3 user name or security name.

Macros

Name

AUTH_LOCALIZED_PASSWORD_KEY_LEN ( see page 439)

INVALID_INDEX ( see page 439)

IS_SNMPV3_AUTH_STRUCTURE ( see page 440)

MSG_AUTHORITATIVE_HEADER_LEN ( see page 440)

Description

SNMPv3 Authentication ( see page 91)

Localized passwed key lenegth size

This is macro INVALID_INDEX.

This is macro

IS_SNMPV3_AUTH_STRUCTURE.

Length of SNMPv3 authoratative msg header length = Header length ( 2 + 2

bytes) + engineID ( snmpEngnIDLength

( see page 434) bytes)

• engine boot( 4 bytes)+ engine time(4 bytes)

+security name

(securityPrimitivesOfIncomingPdu ( see page 432) value) +authentication

parameters

(snmpOutMsgAuthParamLen ( see page 436) value) +privacy parameters

(snmpOutMsgAuthParamLen ( see page 436) value)

326

10.15 SNMP Microchip TCP/IP Stack Help

MSGGLOBAL_HEADER_LEN ( see page 440)

Length of the SNMPv3 msg header(x) =

Header length (2 bytes)

• MSGID size (type(1 byte) + length of value(1 byte)+4 bytes value)

• msgMAXSIZE(type + length of value +4 bytes value)

• msg flag(type + length of value +1 byte value)

• security model type(type + length of value +1 byte value)

PRIV_LOCALIZED_PASSWORD_KEY_LEN ( see page 441)

REPORT_RESPONSE ( see page 441)

SNMP_ENGINE_MAX_MSG_SIZE ( see page 441)

SNMPV3MSG_AUTHENTICATION_SUCCESS ( see page 444)

USER_SECURITY_NAME_LEN ( see page 444)

#define

PRIV_LOCALIZED_PASSWORD_KEY_

LEN

16 SNMPv3 Privacy Pasword key length size

This is macro REPORT_RESPONSE.

SNMP_ENGINE_MAX_MSG_SIZE is determined as the minimum of the max msg size values supported among all of the transports available to and supported by the engine.

SNMP_MAX_MSG_SIZE ( see page 441)

SNMP_MAX_OID_LEN_MEM_USE ( see page 442)

SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE ( see page

442)

SNMP MIN and MAX message 484 bytes in size As per RFC 3411

snmpEngineMaxMessageSize ( see page 433) and RFC 1157 ( section 4-

protocol specification ) and implementation supports more than 484 whenever feasible.

This macro will be used to avoid SNMP

OID memory buffer corruption

This macro will be used to avoid SNMP

OID memory buffer corruption

SNMP_V3 ( see page 442)

This is macro SNMP_V3.

SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE

SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE

SNMPv3 authentication localized Key length for memory validation

SNMPV3_H ( see page 443)

( see page 443)

SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE ( see page

443)

SNMPV3_USM_MAX_USER ( see page 443)

This is macro SNMPV3_H.

SNMPv3 privacy key length size for memory validation

User security name length for memory validation

User Security Model should have atleast

1 user. Default is 3. User should change as per the requirement.

SNMPV3MSG_AUTHENTICATION_FAIL ( see page 444)

This is macro

SNMPV3MSG_AUTHENTICATION_FAI

This is macro

SNMPV3MSG_AUTHENTICATION_SU

CCESS.

SNMPv3 User Security Name length

327

10.15 SNMP Microchip TCP/IP Stack Help

Structs, Records, Enums

Name

AccessCtrlSubSysIsAccessAllowed ( see page 408)

Description

Applications are the typical clients of the service(s) of the Access

Control Subsystem. The following primitive is provided by the

Access Control Subsystem to check if access is allowed:

statusInformation ( see page 422) = -- success or errorIndication

dispatcherProcessPdu ( see page 409) Process Incoming Request or Notification PDU

Dispatcher provides the following primitive to pass an incoming snmp pdu to an application.

dispatcherStatusInfo ( see page 409)

Generate Outgoing Request or Notification

statusInformation ( see page 422) = -- sendPduHandle if success --

errorIndication if failure

dispathcerReturnResponsePdu ( see page 410)

MsgProcModPrepareDataElements ( see page 411)

MsgProcModPrepareOutgoingMessage

MsgProcModPrepareResponseMessage

Generate Outgoing Response

The PDU Dispatcher provides the following primitive for an application to return an SNMP Response PDU to the PDU

Dispatcher: result = SUCCESS or FAILURE

Prepare Data Elements from an Incoming SNMP Message

The Message Processing Subsystem provides this service primitive for preparing the abstract data elements from an incoming SNMP message: result = -- SUCCESS or errorIndication

Prepare Outgoing SNMP Request or Notification Message

The Message Processing Subsystem provides this service primitive for preparing an outgoing SNMP Request or Notification Message

processResponsePdu ( see page 413) Process Incoming Response PDU

Prepare an Outgoing SNMP Response Message

The Message Processing Subsystem provides this service primitive for preparing an outgoing SNMP Response Message: result = --

SUCCESS or FAILURE

The PDU Dispatcher provides the following primitive to pass an incoming SNMP Response PDU to an application: success or errorIndication

registerContextEngineID ( see page

SecuritySysGenerateRequestMsg ( see page 414)

This is record SecuritySysGenerateRequestMsg.

SecuritySysGenerateResponseMsg ( see page 415)

StateRelease ( see page 415)

unregisterContextEngineID ( see page

416)

Generate a Response Message

The Security Subsystem provides the following primitive to generate a Response message:

Release State Reference Information

All Subsystems which pass stateReference information also provide a primitive to release the memory that holds the referenced state information

This is record unregisterContextEngineID.

Types

Name

INOUT_SNMP_PDU ( see page 417)

REPORT_FLAG_AND_SECURITY_LEVEL_FLAGS ( see page 417)

SecuritySysProcessIncomingMsg ( see page 418)

SNMP_ENGNID_OCTET_IDENTIFIER_VAL ( see page

419)

SNMPNONMIBRECDINFO ( see page 419)

Description

This is type INOUT_SNMP_PDU.

This is type

REPORT_FLAG_AND_SECURITY_LEVEL_FLAG

This is type SecuritySysProcessIncomingMsg.

The fifth octet indicates how the rest (6th and following octets) are formatted. Refer to RFC3411 section5 Page# 41

This is type SNMPNONMIBRECDINFO.

328

10.15 SNMP Microchip TCP/IP Stack Help

SNMPV3_HMAC_HASH_TYPE ( see page 419)

SNMPV3_MSG_AUTH_SEC_PARAM_RESULT ( see page 420)

SNMPV3_MSG_PRIV_SEC_PARAM_RESULT ( see page 420)

SNMPV3_PRIV_PROT_TYPE ( see page 420)

Type of hash being calculated

This is type

SNMPV3_MSG_AUTH_SEC_PARAM_RESULT.

This is type

SNMPV3_MSG_PRIV_SEC_PARAM_RESULT.

This is type SNMPV3_PRIV_PROT_TYPE.

SNMPV3_REQUEST_WHOLEMSG ( see page 421)

SNMPV3_RESPONSE_WHOLEMSG ( see page 421) snmpV3EngnUserDataBase ( see page 421)

SNMPV3MSGDATA ( see page 422) snmpV3TrapConfigDataBase ( see page 422) statusInformation ( see page 422)

This is type SNMPV3_REQUEST_WHOLEMSG.

This is type SNMPV3_RESPONSE_WHOLEMSG.

This is type snmpV3EngnUserDataBase.

SNMPv3 snmpv3 target configuration with respect to trap.

success or errorIndication

STD_BASED_SNMP_MESSAGE_PROCESSING_MODEL

( see page 423)

This is type

STD_BASED_SNMP_MESSAGE_PROCESSING

_MODEL.

Snmp Message Processing Model

STD_BASED_SNMP_SECURITY_MODEL ( see page

STD_BASED_SNMPV3_SECURITY_LEVEL ( see page

USM_SECURITY_LEVEL ( see page 424)

This is type

STD_BASED_SNMPV3_SECURITY_LEVEL.

This is type USM_SECURITY_LEVEL.

Variables

Name

authKey_iPad ( see page 426) authKey_oPad ( see page 426)

Description

This is variable authKey_iPad.

This is variable authKey_oPad.

authoritativeSnmpEngineBoots ( see page 426)

authoritativeSnmpEngineTime ( see page 427) cipher_text ( see page 427) deciphered_text ( see page 427)

The number of times that the authoritative SNMP engine has

(re-)initialized itself since its snmpEngineID ( see page 433) was

last configured.

The number of seconds since the value of the

authoritativeSnmpEngineBoots ( see page 426) object last changed

This is variable cipher_text.

This is variable deciphered_text.

getZeroInstance ( see page 427)

This variable is used for gext next request for zero instance

gSnmpV3InPduWholeMsgBuf ( see page 427)

Dynamic memory stub and PDU details for Incoming stored PDU

gSnmpV3OUTPduWholeMsgBuf ( see page 428)

Dynamic memory stub details and constructed outgoing stored PDU details

gSNMPv3PduHeaderBuf ( see page

428)

Response PDU construction offset details

gSNMPv3ScopedPduDataPos ( see page 428) gSNMPv3ScopedPduRequestBuf ( see page 428)

gSNMPv3ScopedPduResponseBuf ( see page 429) gSnmpv3TrapConfigData ( see page

429) gSNMPv3TrapMsgHeaderBuf ( see page 429) gSnmpV3TrapOUTPduWholeMsgBuf

gSNMPv3TrapScopedPduResponseBuf

Offset to read scoped PDU data bytes for processing from dynamic memory stub

Stored request scoped pdu details

Processed response scoped pdu details

SNMPv3 global configuration database to be used for trap notification

TRAP message PDU header construction offset details

Dynamic memory stub details and constructed trap PDU details

329

10.15 SNMP Microchip TCP/IP Stack Help

gSNMPV3TrapSecurityLevel ( see page 430) gSnmpv3UserDBIndex ( see page

TRAP scoped PDU construction offset details

This is variable gSNMPV3TrapSecurityLevel.

430)

Index to the particular reference configured in User security model

data base snmpV3UserDataBase ( see page 437).

gUsmStatsEngineID ( see page 430)

Global variable to find out how many times SNMPv3 engine id has been validated

hmacAuthKeyBuf ( see page 430)

This is variable hmacAuthKeyBuf.

HmacMd5Digest ( see page 431)

HmacSHADigest ( see page 431) incomingPdu ( see page 431) incomingSnmpPDUmsgID ( see page

ivEncrptKeyOut ( see page 431)

This is variable HmacMd5Digest.

This is variable HmacSHADigest.

Incoming PDU details

Retrived Incoming Msg ID value from PDU

This is variable ivEncrptKeyOut.

md5LocalizedAuthKey ( see page 432) This is variable md5LocalizedAuthKey.

msgSecrtyParamLenOffset ( see page

securityPrimitivesOfIncomingPdu ( see page 432) session_key ( see page 432)

This is variable msgSecrtyParamLenOffset.

Incoming PDU Security primitive details.

This is variable session_key.

This is variable sha1LocalizedAuthKey.

sha1LocalizedAuthKey ( see page

433) snmpEngineBoots ( see page 433)

The number of times that the SNMP engine has (re-)initialized itself

since snmpEngineID ( see page 433) was last configured.

snmpEngineID ( see page 433)

Reserving 32 bytes for the snmpEngineID as the octet string length can vary form 5 to 32

The maximum message size the SNMP engine can handle.

snmpEngineMaxMessageSize ( see page 433) snmpEngineMsgProcessModel ( see page 433)

Type of Message processing model used. Value Maximum range

(2^31-1), RFC3411

snmpEngineSecurityModel ( see page

snmpEngineTime ( see page 434)

Type of security model used. Value Maximum range (2^31-1),

RFC3411

The number of seconds since the value of the snmpEngineBoots ( see page 433) object last changed

snmpEngineTimeOffset ( see page

snmpEngnIDLength ( see page 434)

Stores the time value in seconds since SNMP Engine reset

Engine ID length of the SNMP Engine

snmpInMsgAuthParamLen ( see page

snmpInMsgAuthParamStrng ( see page 435)

Incoming SNMPv3 msg authentication parameters string is 12 bytes long.

Reserving 12 bytes for the incoming SNMPv3 msg authentication parameters.

snmpInMsgPrivParamLen ( see page

snmpInMsgPrvParamStrng ( see page

Incoming SNMPv3 msg privacy parameters string is 8 bytes long.

snmpMsgBufSeekPos ( see page 435) Offset to read PDU data bytes for processing from dynamic memory

Reserving 8 bytes for the incoming SNMPv3 msg privacy parameters.

stub

snmpOutMsgAuthParamLen ( see page 436) snmpOutMsgAuthParamStrng ( see page 436) snmpOutMsgPrivParamLen ( see page 436)

Outgoing SNMPv3 msg authentication parameters string is 12 bytes long.

Reserving 12 bytes for the outgoing SNMPv3 msg authentication parameters.

Outgoing SNMPv3 msg privacy parameters string is 8 bytes long.

330

10.15 SNMP Microchip TCP/IP Stack Help SNMP Public Members

snmpOutMsgPrvParamStrng ( see page 436)

snmpResponseSecurityFlag ( see page 437) snmpSecurityLevel ( see page 437) snmpV3AesDecryptInitVector ( see page 437) snmpV3AesEncryptInitVector ( see page 437) snmpV3UserDataBase ( see page

437)

Reserving 8 bytes for the outgoing SNMPv3 msg privacy parameters.

Type of Security for outgoing message in response to the incoming message.

Type of security. noAuthNoPriv(0),AuthNoPriv(1),AuthPriv(3)

128 Bit

This is variable snmpV3UserDataBase.

Description

Simple Network Management Protocol V2c (community) agent implementation of RFC 3416 .

10.15.1

SNMP Public Members

Enumerations

Name

GENERIC_TRAP_NOTIFICATION_TYPE ( see page 333)

Description

This is type GENERIC_TRAP_NOTIFICATION_TYPE.

VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE

( see page 333)

This is type

VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE.

SNMP_ACTION ( see page 333)

This is the list of SNMP action a remote NMS can perform. This inforamtion is passed to application via

callback SNMPValidateCommunity ( see page 341)().

Application should validate the action for given community string.

COMMUNITY_TYPE ( see page 334)

This is type COMMUNITY_TYPE.

Functions

Name

SNMPSendTrap ( see page

336)

Description

Prepare, validate remote node which will receive trap and send trap pdu.

Creates and Sends TRAP pdu.

SNMPNotify ( see page

337)

SNMPSetVar ( see page

338)

SNMPGetVar ( see page

338)

SNMPIsNotifyReady ( see page 339)

SNMPNotifyPrepare ( see page 340)

SNMPGetNextIndex ( see page 340)

SNMPValidateCommunity ( see page 341)

This routine Set the mib variable with the requested value.

Used to Get/collect OID variable information.

Resolves given remoteHost IP address into MAC address.

Collects trap notification info and send ARP to remote host.

To search for next index node in case of a Sequence variable.

Validates community name for access control.

331

10.15 SNMP Microchip TCP/IP Stack Help SNMP Public Members

Macros

Module

OID_MAX_LEN ( see page 342) Change this to match your OID string length.

Structures

Name Description

SNMP_COMMUNITY_MAX_LEN

( see page 342)

This is the maximum length for community string. Application must ensure that this length is observed. SNMP module adds one byte extra after

SNMP_COMMUNITY_MAX_LEN for adding '0' NULL character.

SNMP_START_OF_VAR ( see page 342)

This is macro SNMP_START_OF_VAR.

SNMP_END_OF_VAR ( see page 343)

This is macro SNMP_END_OF_VAR.

SNMP_INDEX_INVALID ( see page 343)

TRAP_TABLE_SIZE ( see page 343)

This is macro SNMP_INDEX_INVALID.

This is macro TRAP_TABLE_SIZE.

TRAP_COMMUNITY_MAX_LEN

( see page 343)

This is macro TRAP_COMMUNITY_MAX_LEN.

NOTIFY_COMMUNITY_LEN ( see page 344)

This is macro NOTIFY_COMMUNITY_LEN.

Name

TRAP_INFO ( see page

335)

Description

This is type TRAP_INFO.

Types

Name

SNMP_INDEX ( see page

342)

Description

SNMP_ID ( see page 342)

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.

This is type SNMP_INDEX.

Unions

Name Description

SNMP_VAL ( see page 334) This is type SNMP_VAL.

Variables

Name

gSendTrapFlag ( see page

335) gSetTrapSendFlag ( see page 335)

Description

global flag to send Trap

#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

Global flag for Generic trap notification

gGenericTrapNotification ( see page 336) gSpecificTrapNotification ( see page 336)

Vendor specific trap code

gOIDCorrespondingSnmpMibID

( see page 336)

Gloabal var to store SNMP ID of var for OID received in SNMP request.

332

10.15 SNMP Microchip TCP/IP Stack Help

Description

The following functions and variables are available to the stack application.

SNMP Public Members

10.15.1.1

GENERIC_TRAP_NOTIFICATION_TYPE Enumeration

File

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.

10.15.1.2

VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE

Enumeration

File

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.

10.15.1.3

SNMP_ACTION Enumeration

File

Snmp GET_RESPONSE ( see page 353) identifier

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;

333

10.15 SNMP Microchip TCP/IP Stack Help SNMP Public Members

Members

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

SNMP_ACTION_UNKNOWN = 0

Description

Snmp GET identifier

Snmp GET_NEXT identifier

Snmp SET identifier

Snmp TRAP identifier

Snmp GET_BULK identifier

Snmp v2 Trap Identifier

Snmp requested action unknown

Description

This is the list of SNMP action a remote NMS can perform. This inforamtion is passed to application via callback

SNMPValidateCommunity ( see page 341)(). Application should validate the action for given community string.

10.15.1.4

COMMUNITY_TYPE Enumeration

File

C typedef enum

{

READ_COMMUNITY = 1,

WRITE_COMMUNITY = 2,

INVALID_COMMUNITY = 3

} COMMUNITY_TYPE;

Members

READ_COMMUNITY = 1

WRITE_COMMUNITY = 2

INVALID_COMMUNITY = 3

Description

This is type COMMUNITY_TYPE.

Description

Read only community

Read write community

Community invalid

10.15.1.5

SNMP_VAL Union

File

C typedef union

{

DWORD dword;

WORD word;

BYTE byte;

BYTE v[

sizeof

(DWORD)];

} SNMP_VAL;

Members

DWORD dword;

WORD word;

Description

double word value word value

334

10.15 SNMP

BYTE byte;

BYTE v[sizeof(DWORD)];

Description

This is type SNMP_VAL.

Microchip TCP/IP Stack Help byte value byte array

10.15.1.6

TRAP_INFO Structure

File

community[TRAP_COMMUNITY_MAX_LEN];

C typedef struct

{

BYTE Size;

struct

{

BYTE communityLen;

char

IP_ADDR IPAddress;

struct

{

unsigned int

bEnabled : 1;

} Flags;

} table[TRAP_TABLE_SIZE];

} TRAP_INFO;

Members

Members Description

BYTE communityLen; Community name length char community[TRAP_COMMUNITY_MAX_LEN];

Community name array

IP_ADDR IPAddress; unsigned int bEnabled : 1;

IP address to which trap to be sent

Trap enabled flag

Description

This is type TRAP_INFO.

10.15.1.7

gSendTrapFlag Variable

File

CustomSNMPApp.c

BYTE gSendTrapFlag = FALSE;

Description

global flag to send Trap

10.15.1.8

gSetTrapSendFlag Variable

File

CustomSNMPApp.c

BYTE gSetTrapSendFlag = FALSE;

SNMP Public Members

335

10.15 SNMP Microchip TCP/IP Stack Help SNMP Public Members

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

10.15.1.9

gGenericTrapNotification Variable

File

CustomSNMPApp.c

BYTE gGenericTrapNotification = ENTERPRISE_SPECIFIC;

Description

Global flag for Generic trap notification

10.15.1.10

gSpecificTrapNotification Variable

File

CustomSNMPApp.c

BYTE gSpecificTrapNotification = VENDOR_TRAP_DEFAULT;

Description

Vendor specific trap code

10.15.1.11

gOIDCorrespondingSnmpMibID Variable

File

CustomSNMPApp.c

BYTE gOIDCorrespondingSnmpMibID = MICROCHIP;

Description

Gloabal var to store SNMP ID of var for OID received in SNMP request.

10.15.1.12

SNMPSendTrap Function

File

SNMPIsNotifyReady ( see page 339)() returns FALSE, this routine times out in 5 seconds. This routine should be modified

C void

SNMPSendTrap();

Returns

None.

336

10.15 SNMP Microchip TCP/IP Stack Help SNMP Public Members

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

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

according to event occured and should update corrsponding OID and notification type to the trap pdu.

Preconditions

If application defined event occurs to send the trap.

10.15.1.13

SNMPNotify Function

File

BOOL SNMPNotify(

SNMPIsNotifyReady ( see page 339)() is already called and returned TRUE.

SNMP_INDEX index

);

Description

The v1 enterprise is mapped directly to SNMPv2TrapOID.0

For ASCII STR trap VAL(argument) contains the pointer address of the string variable.

Remarks

This would fail if there were not UDP socket to open.

Preconditions

Parameters

var val index

Description

SNMP var ID that is to be used in notification

Value of var. Only value of BYTE, WORD or DWORD can be sent.

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

TRUE

FALSE

This would fail under following contions

4) Data type of given var is unknown

Description

if SNMP notification was successful sent. This does not guarantee that remoteHost recieved it.

Notification sent failed.

1) Given SNMP_BIB_FILE does not exist in MPFS 2) Given var does not exist.

3) Previously given agentID does not exist only possible if MPFS itself was corrupted.

337

10.15 SNMP Microchip TCP/IP Stack Help SNMP Public Members

10.15.1.14

SNMPSetVar Function

File

BOOL SNMPSetVar(

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.

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.

Preconditions

OCTET_STRING ( see page 357), ASCII_STRING value is in val->byte;

Parameters

var ref val

Description

Variable id whose value is to be set

Variable reference used to transfer multi-byte data 0 if first byte is set otherwise nonzero value to indicate corresponding byte being set.

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

multi-byte transfer will be performed to transfer remaining bytes of data.

Return Values

TRUE

FALSE

Description

if it is OK to set more byte(s).

if otherwise.

10.15.1.15

SNMPGetVar Function

File

BOOL SNMPGetVar(

SNMP_START_OF_VAR ( see page 342) when very first byte is requested.

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

338

10.15 SNMP appropriate data when called.

Remarks

None.

Preconditions

None

Parameters

var index ref

Microchip TCP/IP Stack Help SNMP Public Members val

Description

Variable id whose value is to be returned

Index of variable that should be transferred

Variable reference used to transfer multi-byte data It is always

Otherwise, use this as a reference to keep track of multi-byte transfers.

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 ( see page 357) transfer data in val->byte using multi-byte

transfer mechanism.

Return Values

TRUE

FALSE

Description

If a value exists for given variable at given index.

Otherwise.

10.15.1.16

SNMPIsNotifyReady Function

File

SNMPNotifyPrepare ( see page 340)() is already called.

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.

Remarks

This would fail if there were not UDP socket to open.

Preconditions

Parameters

remoteHost

Description

Pointer to remote Host IP address

339

10.15 SNMP

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help SNMP Public Members

Description

If remoteHost IP address is resolved and SNMPNotify ( see page 337) may

be called.

If remoteHost IP address is not resolved.

10.15.1.17

SNMPNotifyPrepare Function

File

SNMPInit ( see page 376)() is already called.

C void

SNMPNotifyPrepare(

IP_ADDR* remoteHost,

char

* community,

BYTE communityLen,

SNMP_ID agentIDVar,

BYTE notificationCode,

DWORD timestamp

);

Returns

None

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.

Remarks

This is first of series of functions to complete SNMP notification.

Preconditions

Parameters

remoteHost community communityLen agentIDVar notificaitonCode timestamp

Description

pointer to remote Host IP address

Community string to use to notify

Community string length

System ID to use identify this agent

Notification Code to use

Notification timestamp in 100th of second.

10.15.1.18

SNMPGetNextIndex Function

File

BOOL SNMPGetNextIndex(

SNMP_INDEX* index

);

340

10.15 SNMP Microchip TCP/IP Stack Help SNMP Public Members

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.

Remarks

Only sequence index needs to be handled in this function.

Preconditions

None

Parameters

var index

Return Values

TRUE

FALSE

Description

Variable id whose value is to be returned

Next Index of variable that should be transferred

Description

If a next index value exists for given variable at given index and index parameter contains next valid index.

Otherwise.

10.15.1.19

SNMPValidateCommunity Function

File

SNMPInit ( see page 376) is already called.

BYTE SNMPValidateCommunity(

BYTE * community

);

Returns

This routine returns the community validation result as READ_COMMUNITY or WRITE_COMMUNITY or

INVALID_COMMUNITY

Description

This function validates the community name for the mib access to NMS. The snmp community name received in the request pdu is validated for read and write community names. The agent gives an access to the mib variables only if the community matches with the predefined values. This routine also sets a gloabal flag to send trap if authentication failure occurs.

Remarks

This is a callback function called by module. User application must implement this function and verify that community matches with predefined value. This validation occurs for each NMS request.

Preconditions

Parameters

community

Description

Pointer to community string as sent by NMS.

341

10.15 SNMP Microchip TCP/IP Stack Help SNMP Public Members

10.15.1.20

SNMP_ID Type

File

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.

10.15.1.21

SNMP_INDEX Type

File

C typedef

BYTE SNMP_INDEX;

Description

This is type SNMP_INDEX.

10.15.1.22

SNMP_COMMUNITY_MAX_LEN Macro

File

TCPIP MRF24W.h

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

10.15.1.23

OID_MAX_LEN Macro

File

OID_MAX_LEN (SNMP_MAX_OID_LEN_MEM_USE+1)

#define

Description

Change this to match your OID string length.

10.15.1.24

SNMP_START_OF_VAR Macro

File

342

10.15 SNMP

#define

SNMP_START_OF_VAR (0)

Description

This is macro SNMP_START_OF_VAR.

Microchip TCP/IP Stack Help

10.15.1.25

SNMP_END_OF_VAR Macro

File

#define

SNMP_END_OF_VAR (0xff)

Description

This is macro SNMP_END_OF_VAR.

10.15.1.26

SNMP_INDEX_INVALID Macro

File

#define

SNMP_INDEX_INVALID (0xff)

Description

This is macro SNMP_INDEX_INVALID.

10.15.1.27

TRAP_TABLE_SIZE Macro

File

#define

TRAP_TABLE_SIZE (2)

Description

This is macro TRAP_TABLE_SIZE.

10.15.1.28

TRAP_COMMUNITY_MAX_LEN Macro

File

TRAP_COMMUNITY_MAX_LEN (SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE+1)

#define

Description

This is macro TRAP_COMMUNITY_MAX_LEN.

SNMP Public Members

343

10.15 SNMP Microchip TCP/IP Stack Help

10.15.1.29

NOTIFY_COMMUNITY_LEN Macro

File

TCPIP MRF24W.h

#define

NOTIFY_COMMUNITY_LEN (SNMP_COMMUNITY_MAX_LEN)

Description

This is macro NOTIFY_COMMUNITY_LEN.

SNMP Internal Members

10.15.2

SNMP Internal Members

Enumerations

Name

DATA_TYPE ( see page

350)

SNMP_ERR_STATUS ( see page 361)

Functions

Description

Name Description

_SNMPDuplexInit ( see page 347) Prepare for full duplex transfer.

_SNMPGet ( see page 347)

_SNMPPut ( see page 348)

FindOIDsInRequest ( see page

GetDataTypeInfo ( see page 355) Get ASN data type info.

Read byte from snmp udp socket rx buffer.

Copy byte to tx buffer.

Finds number of varbinds in the varbind list received in a pdu.

IsASNNull ( see page 356)

SetErrorStatus ( see page 360)

Verifies the value type as ASN_NULL ( see page 349).

Set snmp error status in the response pdu.

IsValidLength ( see page 363)

GetNextLeaf ( see page 367)

Retrieves the packet length and actual pdu length.

Searches for the next leaf node in the MIP tree.

GetOIDStringByAddr ( see page

368)

GetOIDStringByID ( see page

368)

IsValidCommunity ( see page

369)

IsValidInt ( see page 369)

IsValidOID ( see page 370)

Get OID string from MPFS using the node address.

Get complete notification variable OID string from MPFS using var id.

Verifies for the community string datatype and the max community name and length, this agent can process.

Verifies variable datatype as INT and retrieves its value.

Populates OID type, length and oid string from the received pdu.

IsValidPDU ( see page 370)

Verifies for the snmp request type.

IsValidStructure ( see page 371)

Decode variable length structure.

OIDLookup ( see page 372)

To search and validate whether the requested OID is in the MIB database.

344

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

ProcessGetSetHeader ( see page 372)

Validates the received udp packet Get/Set request header.

ProcessHeader ( see page 373)

Validates the received udp packet Snmp header.

ProcessSetVar ( see page 374)

Processes snmp Set request pdu.

ProcessVariables ( see page 374) This routine processes the snmp request and parallely creates the

response pdu.

ReadMIBRecord ( see page 375)

Get OID string from MPFS using the node address.

SNMPCheckIfPvtMibObjRequested

( see page 375)

To find whether requested OID is only for private access.

Macros

Name

_SNMPGetTxOffset ( see page 348)

_SNMPSetTxOffset ( see page 349)

AGENT_NOTIFY_PORT ( see page 349)

Description

This is macro _SNMPGetTxOffset.

This is macro AGENT_NOTIFY_PORT.

ASN_INT ( see page 349)

This is macro ASN_INT.

ASN_NULL ( see page 349) This is macro ASN_NULL.

ASN_OID ( see page 350)

This is macro ASN_OID.

DATA_TYPE_TABLE_SIZE

( see page 351)

GET_BULK_REQUEST ( see page 352)

GET_NEXT_REQUEST ( see page 352)

GET_REQUEST ( see page 352)

GET_RESPONSE ( see page 353)

IS_AGENT_PDU ( see page 353)

IS_ASN_INT ( see page

354)

IS_ASN_NULL ( see page

354)

IS_GET_NEXT_REQUEST

( see page 354)

IS_GET_REQUEST ( see page 354)

This is macro GET_BULK_REQUEST.

This is macro GET_NEXT_REQUEST.

This is macro GET_RESPONSE.

This is macro IS_AGENT_PDU.

This is macro IS_ASN_INT.

This is macro IS_ASN_NULL.

This is macro IS_GET_NEXT_REQUEST.

This is macro IS_GET_REQUEST.

IS_GET_RESPONSE ( see page 355)

IS_OCTET_STRING ( see page 355)

IS_OID ( see page 355)

IS_SET_REQUEST ( see page 356)

This is macro IS_GET_RESPONSE.

This is macro IS_OCTET_STRING.

This is macro IS_OID.

This is macro IS_SET_REQUEST.

IS_STRUCTURE ( see page 356)

IS_TRAP ( see page 356)

This is macro IS_TRAP.

345

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

OCTET_STRING ( see page 357)

This is macro OCTET_STRING.

SET_REQUEST ( see page

359)

This is macro SET_REQUEST.

SNMP_AGENT_PORT ( see page 360)

SNMP_BIB_FILE_NAME ( see page 360)

SNMP_COUNTER32 ( see page 361)

SNMP_GAUGE32 ( see page 362)

SNMP_IP_ADDR ( see page 362)

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.

This is macro SNMP_COUNTER32.

This is macro SNMP_GAUGE32.

This is macro SNMP_IP_ADDR.

SNMP_NMS_PORT ( see page 362)

SNMP_NSAP_ADDR ( see page 363)

SNMP_OPAQUE ( see page 364)

SNMP_TIME_TICKS ( see page 364)

This is macro SNMP_NMS_PORT.

This is macro SNMP_NSAP_ADDR.

This is macro SNMP_OPAQUE.

This is macro SNMP_TIME_TICKS.

SNMP_V1 ( see page 365)

SNMP_V2C ( see page 365) This is macro SNMP_V2C.

STRUCTURE ( see page

TRAP ( see page 367)

This is macro TRAP.

Module

DATA_TYPE_INFO ( see page 351)

Structures

Name

OID_INFO ( see page 358)

PDU_INFO ( see page 358)

reqVarErrStatus ( see page

359)

SNMP_NOTIFY_INFO ( see page 363)

Description

Unions

Name

INDEX_INFO ( see page

353)

MIB_INFO ( see page 357)

SNMP_STATUS ( see page

364)

Description

Variables

Name

appendZeroToOID ( see page 349)

Description

global flag to modify OID by appending zero

346

10.15 SNMP Microchip TCP/IP Stack Help

dataTypeTable ( see page

SNMPAgentSocket ( see page 365)

SNMPNotifyInfo ( see page

365)

snmpReqVarErrStatus ( see page 366)

SNMPRxOffset ( see page

SNMPStatus ( see page

SNMPTxOffset ( see page

trapInfo ( see page 367)

ASN format datatype for snmp v1 and v2c

MPFS file handler

Snmp udp socket notify info for trap vars from req list processing err status

Snmp udp buffer rx offset

MIB file access status

Snmp udp buffer tx offset

Initialize trap table with no entries.

Description

The following functions and variables are designated as internal to the SNMP module.

SNMP Internal Members

10.15.2.1

_SNMPDuplexInit Function

File

SNMPTask ( see page 377)() is called.

C void

_SNMPDuplexInit(

UDP_SOCKET socket

);

Returns

None.

Description

As we process SNMP variables, we will prepare response on-the-fly creating full duplex transfer. Current MAC layer does not support full duplex transfer, so SNMP needs to manage its own full duplex connection. Prepare for full duplex transfer.

Set the Tx and Rx offset to start of the buffer.

Remarks

This routine should be called for every new snmp packet received.

Preconditions

Parameters

socket ( see page 185)

Description

An active udp socket for which tx and rx offset to be set.

10.15.2.2

_SNMPGet Function

File

SNMPTask ( see page 377)() is called. A active udp socket is available to read from.

347

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

BYTE _SNMPGet();

Returns

None.

Description

This function reads a single byte from the currently active UDP socket, receive buffer, while incrementing the buffer offset from where the next byte will be read.

Remarks

None.

Preconditions

10.15.2.3

_SNMPGetTxOffset Macro

File

_SNMPGetTxOffset SNMPTxOffset

#define

Description

This is macro _SNMPGetTxOffset.

10.15.2.4

_SNMPPut Function

File

SNMPTask ( see page 377)() is called. A active udp socket is availabe to tx from.

C void

_SNMPPut(

BYTE v

);

Returns

None.

Description

This function writes a single byte to the currently active UDP socket, transmit buffer, while incrementing the buffer offset for the next write operation.

Remarks

None.

Preconditions

348

10.15 SNMP Microchip TCP/IP Stack Help

10.15.2.5

_SNMPSetTxOffset Macro

File

_SNMPSetTxOffset(o) (SNMPTxOffset = o)

#define

Section

SNMP Tx pdu offset settings

10.15.2.6

AGENT_NOTIFY_PORT Macro

File

#define

AGENT_NOTIFY_PORT (0xfffe)

Description

This is macro AGENT_NOTIFY_PORT.

10.15.2.7

appendZeroToOID Variable

File

BYTE appendZeroToOID = FALSE;

Description

global flag to modify OID by appending zero

10.15.2.8

ASN_INT Macro

File

#define

ASN_INT (0x02u)

Description

This is macro ASN_INT.

10.15.2.9

ASN_NULL Macro

File

SNMP Internal Members

349

10.15 SNMP

#define

ASN_NULL (0x05u)

Description

This is macro ASN_NULL.

Microchip TCP/IP Stack Help

10.15.2.10

ASN_OID Macro

File

#define

ASN_OID (0x06u)

Description

This is macro ASN_OID.

10.15.2.11

DATA_TYPE Enumeration

File

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

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

Section

Data Structures and Enumerations

Description

8 bit integer value

16 bit integer value

32 bit integer value

Aray of bytes

Ascii string type

IP address variable

32 bit counter variable

Timer vakue counter variable

32 bit guage variable

Object id value var

Unknown data type

SNMP Internal Members

350

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

************************************************************************

SNMP specific data tyes

10.15.2.12

DATA_TYPE_INFO Structure

File

C typedef struct

{

BYTE asnType;

BYTE asnLen;

} DATA_TYPE_INFO;

Members

BYTE asnType;

BYTE asnLen;

Section

ASN data type info

Description

ASN data type

ASN data length

10.15.2.13

DATA_TYPE_TABLE_SIZE Macro

File

#define

DATA_TYPE_TABLE_SIZE (

sizeof

(dataTypeTable)/

sizeof

(dataTypeTable[0]))

Section

Macros and Definitions

10.15.2.14

dataTypeTable Variable

File

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

10.15.2.15

FindOIDsInRequest Function

File

351

10.15 SNMP Microchip TCP/IP Stack Help

C static

BYTE FindOIDsInRequest(

WORD pdulen

);

Description

This routine is used to find the number of OIDs requested in the received snmp pdu.

Remarks

None.

Preconditions

Parameters

pdulen

Return Values

varCount

Description

Length of snmp pdu request received.

Description

Number of OIDs found in a pdu request.

10.15.2.16

GET_BULK_REQUEST Macro

File

#define

GET_BULK_REQUEST (0xa5)

Description

This is macro GET_BULK_REQUEST.

10.15.2.17

GET_NEXT_REQUEST Macro

File

#define

GET_NEXT_REQUEST (0xa1)

Description

This is macro GET_NEXT_REQUEST.

10.15.2.18

GET_REQUEST Macro

File

#define

GET_REQUEST (0xa0)

SNMP Internal Members

352

10.15 SNMP

Section

SNMP v1 and v2c pdu types

Microchip TCP/IP Stack Help

10.15.2.19

GET_RESPONSE Macro

File

#define

GET_RESPONSE (0xa2)

Description

This is macro GET_RESPONSE.

10.15.2.20

hMPFS Variable

File

MPFS_HANDLE hMPFS;

Description

MPFS file handler

10.15.2.21

INDEX_INFO Union

File

C typedef union

{

struct

{

unsigned int

bIsOID : 1;

} Flags;

BYTE Val;

} INDEX_INFO;

Members

unsigned int bIsOID : 1;

BYTE Val;

Section

SNMP OID index information

Description

value is OID/index int flag value is OID/index byte flag

10.15.2.22

IS_AGENT_PDU Macro

File

IS_AGENT_PDU(a) (a==GET_REQUEST || \

SNMP Internal Members

353

10.15 SNMP Microchip TCP/IP Stack Help

#define

a==GET_NEXT_REQUEST || \

a==SET_REQUEST || \

a==SNMP_V2C_GET_BULK)

Description

This is macro IS_AGENT_PDU.

10.15.2.23

IS_ASN_INT Macro

File

IS_ASN_INT(a) (a==ASN_INT)

#define

Description

This is macro IS_ASN_INT.

10.15.2.24

IS_ASN_NULL Macro

File

IS_ASN_NULL(a) (a==ASN_NULL)

#define

Description

This is macro IS_ASN_NULL.

10.15.2.25

IS_GET_NEXT_REQUEST Macro

File

IS_GET_NEXT_REQUEST(a) (a==GET_NEXT_REQUEST)

#define

Description

This is macro IS_GET_NEXT_REQUEST.

10.15.2.26

IS_GET_REQUEST Macro

File

IS_GET_REQUEST(a) (a==GET_REQUEST)

#define

Description

This is macro IS_GET_REQUEST.

SNMP Internal Members

354

10.15 SNMP Microchip TCP/IP Stack Help

10.15.2.27

IS_GET_RESPONSE Macro

File

IS_GET_RESPONSE(a) (a==GET_RESPONSE)

#define

Description

This is macro IS_GET_RESPONSE.

10.15.2.28

IS_OCTET_STRING Macro

File

IS_OCTET_STRING(a) (a==OCTET_STRING)

#define

Description

This is macro IS_OCTET_STRING.

10.15.2.29

IS_OID Macro

File

IS_OID(a) (a==ASN_OID)

#define

Description

This is macro IS_OID.

10.15.2.30

GetDataTypeInfo Function

File

DATA_TYPE_INFO * info

BOOL GetDataTypeInfo(

DATA_TYPE dataType,

);

Returns

TRUE - success FALSE - failure

Description

This routine validates the SNMP GEt dtat type and collects ASN data type value to the info.

Remarks

None.

SNMP Internal Members

355

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

Preconditions

matching data type info w.r.t dataTypeTable ( see page 351)

Parameters

dataType info

Description

SNMP pdu data type info.

10.15.2.31

IS_SET_REQUEST Macro

File

IS_SET_REQUEST(a) (a==SET_REQUEST)

#define

Description

This is macro IS_SET_REQUEST.

10.15.2.32

IS_STRUCTURE Macro

File

IS_STRUCTURE(a) (a==STRUCTURE)

#define

Section

SNMP specific data validation

10.15.2.33

IS_TRAP Macro

File

#define

IS_TRAP(a) (a==TRAP)

Description

This is macro IS_TRAP.

10.15.2.34

IsASNNull Function

File

For Get,Get_Next,Get_Bulk snmp reuest, the var bind the value data type should be ASN_NULL ( see page 349) and

C static

BOOL IsASNNull();

Description

356

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members value field must be NULL and . This routine verifies the data type and value fields in the received requests. The SET

request, the value data type can not be ASN_NULL ( see page 349), otherwise the snmp request is not processed.

Remarks

None.

Preconditions

None

Parameters

TRUE

FALSE

Description

If value type is ASN_NULL ( see page 349) and value is NULL.

If data type and value is other than ASN_NULL ( see page 349) and NULL

resp.

10.15.2.35

MIB_INFO Union

File

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

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;

BYTE Val;

Section

SNMP object information

Description

Object have distant sibling node

Object is constant

Object is sequence

Sibling node flag

Node is parent flag

Node is editable flag

Node have agent id flag

Id present flag

MIB Obj info as byte value

10.15.2.36

OCTET_STRING Macro

File

357

10.15 SNMP

#define

OCTET_STRING (0x04u)

Description

This is macro OCTET_STRING.

Microchip TCP/IP Stack Help

10.15.2.37

OID_INFO Structure

File

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

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;

Section

SNMP MIB variable object information

Description

Node location in the mib

Object Id

Node info

Data type

Snmp Id

Data length

Data

Sibling info

Child info

Index of object

Index length

10.15.2.38

PDU_INFO Structure

File

C typedef struct

{

DWORD_VAL requestID;

BYTE nonRepeators;

BYTE maxRepetitions;

BYTE pduType;

BYTE errorStatus;

BYTE erroIndex;

SNMP Internal Members

358

10.15 SNMP

BYTE snmpVersion;

WORD pduLength;

} PDU_INFO;

Members

DWORD_VAL requestID;

BYTE nonRepeators;

BYTE maxRepetitions;

BYTE pduType;

BYTE errorStatus;

BYTE erroIndex;

BYTE snmpVersion;

WORD pduLength;

Section

SNMP pdu information database

Microchip TCP/IP Stack Help

Description

Snmp request id non repeaters in the request max repeaters in the request

Snmp pdu type

Pdu error status

Pdu error Index

Snmp version

Pdu length

10.15.2.39

reqVarErrStatus Structure

File

C typedef struct

{

WORD noSuchObjectErr;

WORD noSuchNameErr;

WORD noSuchInstanceErr;

WORD endOfMibViewErr;

} reqVarErrStatus;

Members

WORD noSuchObjectErr;

WORD noSuchNameErr;

WORD noSuchInstanceErr;

WORD endOfMibViewErr;

Section

SNMP reuested variable list error status information.

Max variable in a request supported 15

Description

Var list no such obj errors flags

Var list no such name error

Var list no such instance error

Var list end of mib view error

10.15.2.40

SET_REQUEST Macro

File

#define

SET_REQUEST (0xa3)

Description

This is macro SET_REQUEST.

SNMP Internal Members

359

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

10.15.2.41

SetErrorStatus Function

File

SNMP_ERR_STATUS errorStatus,

C void

SetErrorStatus(

WORD errorStatusOffset,

WORD errorIndexOffset,

BYTE errorIndex

);

Returns

None.

Description

This routine processes the received snmp Get request pdu for the variable binding in the request and also creates the response pdu.

Remarks

None.

Preconditions

Parameters

errorStatusOffset errorIndexOffset errorStatus errorIndex

Description

Offset to update error status in Response Tx pdu

Offset to update error index

Snmp process error to be updated in response.

Index of the request varbind in the var bind list for which error status is to be updated.

10.15.2.42

SNMP_AGENT_PORT Macro

File

#define

SNMP_AGENT_PORT (161)

Section

SNMP Udp ports

10.15.2.43

SNMP_BIB_FILE_NAME Macro

File

#define

SNMP_BIB_FILE_NAME "snmp.bib"

360

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

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.

10.15.2.44

SNMP_COUNTER32 Macro

File

#define

SNMP_COUNTER32 (0x41)

Description

This is macro SNMP_COUNTER32.

10.15.2.45

SNMP_ERR_STATUS Enumeration

File

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

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

Description

Snmp no error

Value too big error

No such name in MIB error

Not assignable value for the var error

Read only variable, write not allowed err

Snmp gen error

Access to modify or read not granted err

Variable data type wrong error

Wrong data length error

361

10.15 SNMP

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

Section

SNMP specific errors

Microchip TCP/IP Stack Help

Wrong encoding error

Wrong value for the var type

No creationg error

Inconsistent value error

Resource unavailbe error

Modification update failed error

Modification undo failed

Authorization failed error

Variable read only

Inconsistent name

No such object error

No such instance error

Reached to end of mib error

10.15.2.46

SNMP_GAUGE32 Macro

File

#define

SNMP_GAUGE32 (0x42)

Description

This is macro SNMP_GAUGE32.

10.15.2.47

SNMP_IP_ADDR Macro

File

#define

SNMP_IP_ADDR (0x40)

Description

This is macro SNMP_IP_ADDR.

10.15.2.48

SNMP_NMS_PORT Macro

File

#define

SNMP_NMS_PORT (162)

Description

This is macro SNMP_NMS_PORT.

SNMP Internal Members

362

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

10.15.2.49

SNMP_NOTIFY_INFO Structure

File

community[NOTIFY_COMMUNITY_LEN];

C typedef struct

{

char

BYTE communityLen;

SNMP_ID agentIDVar;

BYTE notificationCode;

UDP_SOCKET socket;

DWORD_VAL timestamp;

SNMP_ID trapIDVar;

} SNMP_NOTIFY_INFO;

Members

char community[NOTIFY_COMMUNITY_LEN];

BYTE communityLen;

SNMP_ID agentIDVar;

BYTE notificationCode;

UDP_SOCKET socket;

DWORD_VAL timestamp;

SNMP_ID trapIDVar;

Description

Community name array

Community name length

Agent id for trap identification

Trap notification code

Udp socket number

Time stamp for trap

SNMPV2 specific trap

Section

SNMP trap notification information for agent

10.15.2.50

SNMP_NSAP_ADDR Macro

File

#define

SNMP_NSAP_ADDR (0x45)

Description

This is macro SNMP_NSAP_ADDR.

10.15.2.51

IsValidLength Function

File

BYTE IsValidLength(

WORD * len

);

Description

Checks current packet and returns total length value as well as actual length bytes.We do not support any length byte count of more than 2 i.e. total length value must not be more than 16-bit.

363

10.15 SNMP

Remarks

None.

Preconditions

None

Parameters

len

Return Values

lengthBytes

Microchip TCP/IP Stack Help

Description

Pointer to memory where actual length is stored.

Description

Total length bytes are 0x80 itself plus tempData.

10.15.2.52

SNMP_OPAQUE Macro

File

#define

SNMP_OPAQUE (0x44)

Description

This is macro SNMP_OPAQUE.

10.15.2.53

SNMP_STATUS Union

File

C typedef union

{

struct

{

unsigned int

bIsFileOpen : 1;

} Flags;

BYTE Val;

} SNMP_STATUS;

Members

unsigned int bIsFileOpen : 1;

BYTE Val;

Section

SNMP specific mib file access information

Description

MIB file access int flag

MIB file access byte flag

10.15.2.54

SNMP_TIME_TICKS Macro

File

#define

SNMP_TIME_TICKS (0x43)

SNMP Internal Members

364

10.15 SNMP

Description

This is macro SNMP_TIME_TICKS.

Microchip TCP/IP Stack Help

10.15.2.55

SNMP_V1 Macro

File

#define

SNMP_V1 (0)

Section

SNMP agent version types

10.15.2.56

SNMP_V2C Macro

File

#define

SNMP_V2C (1)

Description

This is macro SNMP_V2C.

10.15.2.57

SNMPAgentSocket Variable

File

UDP_SOCKET SNMPAgentSocket = INVALID_UDP_SOCKET;

Description

Snmp udp socket

10.15.2.58

SNMPNotifyInfo Variable

File

SNMP_NOTIFY_INFO SNMPNotifyInfo;

Description

notify info for trap

SNMP Internal Members

365

10.15 SNMP Microchip TCP/IP Stack Help

10.15.2.59

snmpReqVarErrStatus Variable

File

reqVarErrStatus snmpReqVarErrStatus;

Description

vars from req list processing err status

10.15.2.60

SNMPRxOffset Variable

File

WORD SNMPRxOffset = 0;

Description

Snmp udp buffer rx offset

10.15.2.61

SNMPStatus Variable

File

SNMP_STATUS SNMPStatus;

Description

MIB file access status

10.15.2.62

SNMPTxOffset Variable

File

WORD SNMPTxOffset;

Description

Snmp udp buffer tx offset

10.15.2.63

STRUCTURE Macro

File

SNMP Internal Members

366

10.15 SNMP

#define

STRUCTURE (0x30u)

Section

SNMP specific variables

Microchip TCP/IP Stack Help

10.15.2.64

TRAP Macro

File

TRAP_INFO trapInfo = { TRAP_TABLE_SIZE };

#define

TRAP (0xa4)

Description

This is macro TRAP.

10.15.2.65

trapInfo Variable

File

CustomSNMPApp.c

Description

Initialize trap table with no entries.

SNMP Internal Members

10.15.2.66

GetNextLeaf Function

File

ProcessGetBulkVar ( see page 383)() else ProcessGetNextVar ( see page 384)() is called.

BOOL GetNextLeaf(

OID_INFO* rec

);

Description

This routine searches for the next leaf node from the current node. The input to this function is the node from where next leaf node is to be located. The next leaf node will be a silbing else distant sibling or leaf node of next branch, if any present. The input parameter var pointer will be updated with the newly found leaf node OID info.

Remarks

None.

Preconditions

Parameters

rec

Description

Pointer to SNMP MIB variable object information

367

10.15 SNMP

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help

Description

If next leaf node is found.

There is no next leaf node.

SNMP Internal Members

10.15.2.67

GetOIDStringByAddr Function

File

BOOL GetOIDStringByAddr(

BYTE* oidString,

BYTE* len

);

Description

This routine is called when a OID string is required to be searched from MPFS using node address.

Remarks

None.

Preconditions

None.

Parameters

rec oidString len

Return Values

TRUE

FLASE

Description

Pointer to SNMP MIB variable object information

Pointer to store the string of OID searched

Oid length

Description

If oid string is found.

Otherwise.

10.15.2.68

GetOIDStringByID Function

File

TRAP pdu is send with this OID corresponding to the SNMP_ID ( see page 342) used by the agent application to send the

BOOL GetOIDStringByID(

SNMP_ID id,

OID_INFO* info,

BYTE* oidString,

BYTE* len

);

Description

This routine is called when a OID string is required to be searched from MPFS using agent id. The string is saved with agent.

pdu.

368

10.15 SNMP Microchip TCP/IP Stack Help

Remarks

This function is used only when TRAP is enabled.

Parameters

id info oidString len

Return Values

TRUE

FLASE

Description

System ID to use identify this agent.

Pointer to SNMP MIB variable object information

Pointer to store the string of OID serached

Oid length

Description

If oid string is found for the variable id in MPFS.

Otherwise.

SNMP Internal Members

10.15.2.69

IsValidCommunity Function

File

C static

BOOL IsValidCommunity(

char

* community,

BYTE* len

);

Description

This routine populates and validates the community datatype, community name and length from the received snmp request pdu. Community name is used for accessing public and private memebrs of the mib.

Remarks

None.

Preconditions

Parameters

community len

Return Values

TRUE

FALSE

Description

Pointer to memory where community string will be stored.

Pointer to memory where comunity length gets stored.

Description

If valid community received.

If community is not valid.

10.15.2.70

IsValidInt Function

File

This routine populates and validates the received variable for the data type as "ASN_INT ( see page 349)" and the data

BOOL IsValidInt(

369

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

DWORD* val

);

Description

length for max 4 bytes.

Remarks

None.

Preconditions

ProcessHeader ( see page 373)() or ProcessGetSetHeader ( see page 372)() is called.

Parameters

val

ReturnValues

FALSE

Description

Pointer to memory where int var value will be stored.

TRUE - If valid integer type and value is received.

Other than integer data type and value received .

10.15.2.71

IsValidOID Function

File

In this routine, OID data type "ASN_OID ( see page 350)" is verified in the received pdu. If the data type is matched, then

C static

BOOL IsValidOID(

BYTE* oid,

BYTE* len

);

Description

only var bind is processed. OID length and OID is populated. The max OID length can be 15.

Remarks

None.

Preconditions

ProcessVariabels() is called.

Parameters

oid len

Return Values

TRUE

FALSE

Description

Pointer to memory to store the received OID string

Pointer to memory to store OID length

Description

If value type is ASN_OID ( see page 350) and oid length not more than 15.

Otherwise.

10.15.2.72

IsValidPDU Function

File

370

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

C static

BOOL IsValidPDU(

SNMP_ACTION* pdu

);

Description

This routine populates and verifies for the received snmp request pdu type.

Remarks

None.

Preconditions

Parameters

val

Return Values

TRUE

FALSE

Description

Pointer to memory where received snmp request type is stored.

Description

If this snmp request can be processed by the agent.

If the request can not be processed.

10.15.2.73

IsValidStructure Function

File

This routine is used to verify whether the received varbind is of type STRUCTURE ( see page 366) and to find out the

BYTE IsValidStructure(

WORD* dataLen

);

Description

variable binding structure length.

Remarks

None.

Preconditions

If variable data structure is not type STRUCTURE ( see page 366).

Parameters

datalen

Return Values

headrbytes

FALSE

Description

Pointer to memory to store OID structure length.

Description

Variable binding length.

371

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

10.15.2.74

OIDLookup Function

File

BYTE OIDLookup(

BYTE* oid,

BYTE oidLen,

OID_INFO* rec

);

Description

The MIB database is stored with the agent in binary mib format. This is the binary mib format: , , ...>]}, ChildNode variable bind name is a dotted string of oid. Every oid is a node in the MIB tree and have varied information. This routine on reception of the snmp request, will search for every oid in the var name. This routine will return information whether the requested var name is part of the MIB tree data structre of this agent or not.

Remarks

This routine works for the MPFS2 mib storage format. It uses the MPFS2 APIs to read,search and collect information from the mib database.

Preconditions

Valid snmp request with valid OID format is received.

Parameters

pduDbPtr oid oidLen rec

Return Values

TRUE

FALSE

Description

Pointer to received snmp pdu elements information

Pointer to the string of OID to be searched

Oid length

Pointer to SNMP MIB variable object information

Description

If the complete OID string is found in the mib

If complete OID do not match. Also different erros returned are

SNMP_END_OF_MIB_VIEW SNMP_NO_SUCH_NAME

SNMP_NO_SUCH_OBJ SNMP_NO_SUCH_INSTANCE

10.15.2.75

ProcessGetSetHeader Function

File

C static

BOOL ProcessGetSetHeader(

ProcessHeader ( see page 373)() is called and returns pdu type and do not returns SNMP_ACTION_UNKNOWN

);

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.

372

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

Remarks

The request pdu will be processed only if this routine returns TRUE

Preconditions

Parameters

Description

Pointer to received pdu information database.

Parameters

pduDbPtr

Return Values

TRUE

FALSE

Description

If the received request header is validated and passed.

If rxed request header is not valid.

10.15.2.76

ProcessHeader Function

File

SNMP_ACTION ProcessHeader(

C static

Collects PDU_INFO ( see page 358) (SNMP pdu information database),community name, community length and length of

char

* community,

BYTE* len

);

Description

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.

Remarks

The received pdu will be processed only if this routine returns the pdu type else the pdu is discarded as not Snmp pdu.

Preconditions

UDPIsGetReady ( see page 620)(SNMPAgentSocket ( see page 365)) is called in SNMPTask ( see page 377)(), it

check if there is any packet on SNMP Agent socket, should return TRUE.

Parameters

pduDbPtr community len

Return Values

SNMP_ACTION ( see page 333)

Description

Pointer to received pdu information database

Pointer to var storing, community string in rxed pdu

Pointer to var storing, community string length rxed in pdu

Description

Snmp request pdu type.

373

10.15 SNMP Microchip TCP/IP Stack Help SNMP Internal Members

10.15.2.77

ProcessSetVar Function

File

BYTE ProcessSetVar(

SNMP_ERR_STATUS* errorStatus

);

Description

This routine processes the received snmp set request pdu for the variable binding in the request and also creates the response pdu.

Remarks

None.

Preconditions

Parameters

pduDbPtr rec errorStatus

Return Values

copiedBytes

Description

Received pdu information database pointer

Pointer to SNMP MIB variable object information

Pointer to update error status info

Description

Number of bytes copied by this routine to the snmp pdu tx buffer.

10.15.2.78

ProcessVariables Function

File

C static

BOOL ProcessVariables(

The received udp packet is varified as SNMP request. ProcessHeader ( see page 373)() and ProcessGetSetHeader ( see page 372)() returns but FALSE.

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.

Remarks

None

Preconditions

374

10.15 SNMP

Parameters

pduDbPtr community len

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help SNMP Internal Members

Description

Pointer to received pdu information database

Pointer to var, storing community string in rxed pdu

Pointer to var, storing community string length rxed in pdu

Description

If the snmp request processing is successful.

If the processing failed else the processing is not completed.

10.15.2.79

ReadMIBRecord Function

File

GetOIDStringByID ( see page 368)() or GetOIDStringByAddr ( see page 368)() is called.

C static void

ReadMIBRecord(

DWORD h,

OID_INFO* rec

);

Returns

None.

Description

This routine is called when a OID string is required to be searched from MPFS using node address.

Remarks

None.

Preconditions

Parameters

h rec

Description

Node adderess whose oid is to be read.

Pointer to store SNMP MIB variable object information

10.15.2.80

SNMPCheckIfPvtMibObjRequested Function

File

C static

BOOL SNMPCheckIfPvtMibObjRequested(

BYTE* OIDValuePtr

);

Description

This routine is used to find whether requested object belongs to the private object group of the mib of agent. If yes, then that mib object can be accessed only with private community (supported in SNMPv2c).

375

10.15 SNMP Microchip TCP/IP Stack Help

Remarks

None.

Preconditions

SNMPTask ( see page 377) Polls for every snmp pdu received.

Parameters

Description

Pointer to memory stored with received OID.

Parameters

OIDValuePtr

Return Values

TRUE

FLASE

Description

If the requested object is of private branch of the mib.

If the requested object is publically accessible.

SNMP Stack Members

10.15.3

SNMP Stack Members

Functions

Name Description

SNMPInit ( see page 376)

Initialize SNMP module internals.

Module

Description

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.

10.15.3.1

SNMPInit Function

File

At least one UDP socket must be available. UDPInit ( see page 627)() is already called.

C void

SNMPInit();

Returns

None

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.

Remarks

This function is called only once during lifetime of the application. One UDP socket will be used.

Preconditions

376

10.15 SNMP Microchip TCP/IP Stack Help Functions

10.15.3.2

SNMPTask Function

File

SNMPInit ( see page 376)() is already called.

BOOL SNMPTask();

Description

Handle incoming SNMP requests as well as any outgoing SNMP responses and timeout conditions.

Remarks

None

Preconditions

Return Values

TRUE

FALSE

Description

If SNMP module has finished with a state

If a state has not been finished.

10.15.4

Functions

Functions

Name

_IsSNMPv3ValidStructure ( see page 379)

_Snmpv3IsValidAuthStructure ( see page 379)

_Snmpv3IsValidInt ( see page 380)

FindOIDsFromSnmpV3Request ( see page 381) getSnmpV2GenTrapOid ( see page 381)

IsSnmpV3ASNNull ( see page 382)

IsSnmpv3ValidOID ( see page 382)

IsSNMPv3ValidStructure ( see page 383)

ProcessGetBulkVar ( see page 383)

ProcessGetNextVar ( see page 384)

ProcessGetVar ( see page 385)

ProcessSnmpv3MsgData ( see page 385)

SNMPGetExactIndex ( see page 386)

Description

Decode variable length structure.

Verifies variable datatype as INT and retrieves its value.

Finds number of varbinds in the varbind list received in a SNMPv3 pdu.

Resolves generic trap code to generic trap OID.

Verifies the value type as ASN_NULL ( see page 349).

Populates OID type, length and oid string from the received pdu.

Decode variable length structure.

This routine process the SNMPv2c Get Bulk Request.

Retrieves next node from the MIB database.

Processes snmp Get request pdu.

This routine processes the snmpv3 request and parallely creates the response pdu.

To search for exact index node in case of a Sequence variable.

377

10.15 SNMP Microchip TCP/IP Stack Help Functions

SNMPIdRecrdValidation ( see page 386)

SNMPIsValidSetLen ( see page 387)

Used to Restrict the access dynamic and non dynamic

OID string for A perticular SNMP Version.

Validates the set variable data length to data type.

Snmpv3AESDecryptRxedScopedPdu ( see page

388)

Snmpv3AESEncryptResponseScopedPdu ( see page 388)

Incoming SNMPv3 scoped PDU decryption using AES decryption protocol.

outGoing SNMPv3 scoped PDU Encryption using AES encryption protocol.

Snmpv3AuthenticateRxedPduForDataIntegrity ( see page 389)

Authenticate an incoming SNMPV3 USM PDU using

MD5 or SHA

Snmpv3AuthenticateTxPduForDataIntegrity ( see page 389)

Authenticate to an outgoing SNMPV3 USM PDU using

MD5 or SHA

Snmpv3AuthKeyZeroing2HmacBufLen64 ( see page 390)

Snmpv3BufferPut ( see page 390)

Pad zero to the authentication key localized buffer.

Snmpv3CmprTrapSecNameAndSecLvlWithUSMDb

Snmpv3ComputeHMACIpadOpadForAuthLoclzedKey

Copies BYTE data to dynamically allocated memory buffer.

Routine to find the index of the user name in the user data base table.

Snmpv3ComputeHmacMD5Digest ( see page 392)

Compute HMAC inner and outer pad for authorization localized key.

Compute HMAC - MD5 authentication code

Snmpv3ComputeHmacShaDigest ( see page 393)

Compute HMAC - SHA authentication code

Snmpv3ComputeMd5HmacCode ( see page 393)

Compute HMAC - MD5 authentication code

Snmpv3ComputeShaHmacCode ( see page 394)

Snmpv3FormulateEngineID ( see page 394)

Compute HMAC - SHA authentication code

Formulates the snmpEngineID ( see page 433) for the

SNMPV3 engine.

Snmpv3FreeDynAllocMem ( see page 395)

Snmpv3GetAuthEngineTime ( see page 395)

Snmpv3GetBufferData ( see page 396)

Snmpv3GetSecurityLevel ( see page 396)

Snmpv3GetTrapSecurityLevel ( see page 397)

Allocated dynamic memory freeing is done by this routine.

Updates the snmp engine time variable

'snmpEngineTime ( see page 434)' for the SNMPV3

engine.

Reads BYTE data from dynamically allocated memory buffer.

Get Security level from authentication and Privacy type.

Routine to find the report, auth and privacy flags settings in the TRAP.

Snmpv3Init ( see page 397)

Snmpv3InitializeUserDataBase ( see page 398)

Snmpv3IsValidAuthStructure ( see page 398)

Snmpv3IsValidInt ( see page 399)

Snmpv3MsgProcessingModelProcessPDU ( see page 399)

SNMPv3 initialization.

Intialize default SNMPv3 global user database.

Decode variable length structure.

Verifies variable datatype as INT and retrieves its value.

This routine collects or populates the message processing model infomation from the received

SNMPv3 request PDU or to the response PDU respectively.

Snmpv3Notify ( see page 400)

Creates and Sends SNMPv3 TRAP pdu.

Snmpv3Pswd2LocalizedAuthKeyMD5Hashing ( see page 400)

Convert MD5 Auth password to the localized Key using

SNMPEngineID.

Snmpv3Pswd2LocalizedAuthKeySHAHashing ( see page 401)

Snmpv3ReportPdu ( see page 401)

Convert SHA Auth password to the localized Key using

SNMPEngineID.

Constructs the report pdu infomration for the Report

Pdu.

Snmpv3ScopedPduProcessing ( see page 402)

Snmpv3SetErrorStatus ( see page 402)

This routine collects the scoped pdu header information from the received SNMPv3 request PDU or populates to the response PDU respectively.

Set snmpv3 error status in the response pdu.

378

10.15 SNMP Microchip TCP/IP Stack Help Functions

Snmpv3TrapScopedpdu ( see page 403)

Snmpv3UserSecurityModelProcessPDU ( see page

404)

Snmpv3UsmAesEncryptDecryptInitVector ( see page 404)

TRAP PDU scoped pdu header construction.

This routine collects or populates the security model parametrs infomation from the received SNMPv3 request PDU or to the response PDU respectively.

AES Encryption and decryption init vector.(RFC 3826 )

Snmpv3UsmOutMsgAuthenticationParam ( see page 405)

Snmpv3USMOutMsgPrivParam ( see page 405)

Snmpv3UsmSnmpEngnAuthPrivPswdLocalization ( see page 405)

Snmpv3ValidateEngineId ( see page 406)

Snmpv3ValidateSecNameAndSecLvl ( see page

406)

Snmpv3ValidateSecurityName ( see page 407)

Both MD5 and SHA1 is used for the outgoing message authentication.

SNMP USM out message uses Privacy protocol (RFC

3826 )

Convert Auth and Priv password to the localized Key using SNMPEngineID.

Validate engine ID.

Vaidate security name with Security level.

Validate SNMPV3 user name or security name.

Module

10.15.4.1

_IsSNMPv3ValidStructure Function

File

This routine populates and validates the received variable for the data type as "STRUCTURE ( see page 366)" and the

BOOL _IsSNMPv3ValidStructure(

UINT8* wholeMsgPtr,

WORD* pos,

WORD* dataLen

);

Description

data length for max 4 bytes.

Remarks

None.

Preconditions

None

Parameters

wholeMsgPtr pos val

ReturnValues

FALSE

Description

Pointer to memory where int var value is be stored.

position in the memory buffer where data taype to be varified is stored

Pointer to memory where int var value will be stored.

TRUE - If valid integer type and value is received.

Other than integer data type and value received .

10.15.4.2

_Snmpv3IsValidAuthStructure Function

File

This routine is used to verify whether the received varbind is of type STRUCTURE ( see page 366) and to find out the

379

10.15 SNMP Microchip TCP/IP Stack Help Functions

BYTE _Snmpv3IsValidAuthStructure(

WORD* dataLen

);

Description

variable binding structure length. This rotuine only refers to the incoming snmpv3 request dynamically allocated memory

buffer 'gSnmpV3InPduWholeMsgBuf ( see page 427)' .

Remarks

None.

Preconditions

If variable data structure is not type STRUCTURE ( see page 366).

Parameters

Description

Pointer to memory to store OID structure length.

Parameters

datalen

Return Values

headrbytes

FALSE

Description

Variable binding length.

10.15.4.3

_Snmpv3IsValidInt Function

File

This routine populates and validates the received variable for the data type as "ASN_INT ( see page 349)" and the data

BOOL _Snmpv3IsValidInt(

UINT8 * wholeMsgPtr,

WORD* pos,

DWORD* val

);

Description

length for max 4 bytes.

Remarks

None.

Preconditions

None

Parameters

wholeMsgPtr pos val

ReturnValues

FALSE

Description

Pointer to memory where int var value is be stored.

position in the memory buffer where data taype to be varified is stored

Pointer to memory where int var value will be stored.

TRUE - If valid integer type and value is received.

Other than integer data type and value received .

380

10.15 SNMP Microchip TCP/IP Stack Help

10.15.4.4

FindOIDsFromSnmpV3Request Function

File

C static

BYTE FindOIDsFromSnmpV3Request(

WORD pdulen

);

Description

This routine is used to find the number of OIDs requested in the received snmp pdu.

Remarks

None.

Preconditions

Parameters

pdulen

Return Values

varCount

Description

Length of snmp pdu request received.

Description

Number of OIDs found in a pdu request.

10.15.4.5

getSnmpV2GenTrapOid Function

File

This would fail if generic_trap_code is not coming under GENERIC_TRAP_NOTIFICATION_TYPE ( see page 333)

BYTE * getSnmpV2GenTrapOid(

BYTE generic_trap_code,

BYTE * len

);

Description

This function resolves given generic trap code to generic trap OID.

Remarks

Preconditions

SNMPNotifyPrepare ( see page 340)() is already called.

Parameters

generic_trap_code len

Return Values

BYTE *

Description

GENERIC_TRAP_NOTIFICATION_TYPE ( see page 333)

generic trap OID length

Description

TRAP OID

Functions

381

10.15 SNMP Microchip TCP/IP Stack Help Functions

10.15.4.6

IsSnmpV3ASNNull Function

File

For Get,Get_Next,Get_Bulk snmp reuest, the var bind the value data type should be ASN_NULL ( see page 349) and

C static

BOOL IsSnmpV3ASNNull();

Description

value field must be NULL and . This routine verifies the data type and value fields in the received requests. The SET

request, the value data type can not be ASN_NULL ( see page 349), otherwise the snmp request is not processed. This

rotuine only refers to the incoming snmpv3 request dynamically allocated memory buffer 'gSNMPv3ScopedPduRequestBuf

( see page 428)' .

Remarks

None.

Preconditions

None

Parameters

TRUE

FALSE

Description

If value type is ASN_NULL ( see page 349) and value is NULL.

If data type and value is other than ASN_NULL ( see page 349) and NULL

resp.

10.15.4.7

IsSnmpv3ValidOID Function

File

In this routine, OID data type "ASN_OID ( see page 350)" is verified in the received pdu. If the data type is matched, then

C static

BOOL IsSnmpv3ValidOID(

BYTE* oid,

BYTE* len

);

Description

only var bind is processed. OID length and OID is populated. The max OID length can be 15.

Remarks

None.

Preconditions

ProcessVariabels() is called.

Parameters

oid len

Description

Pointer to memory to store the received OID string

Pointer to memory to store OID length

382

10.15 SNMP

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help Functions

Description

If value type is ASN_OID ( see page 350) and oid length not more than 15.

Otherwise.

10.15.4.8

IsSNMPv3ValidStructure Function

File

This routine is used to verify whether the received varbind is of type STRUCTURE ( see page 366) and to find out the

BOOL IsSNMPv3ValidStructure(

WORD* dataLen

);

Description

variable binding structure length. This rotuine only refers to the incoming snmpv3 request dynamically allocated memory

buffer 'gSNMPv3ScopedPduRequestBuf ( see page 428)' .

Remarks

None.

Preconditions

If variable data structure is not type STRUCTURE ( see page 366).

Parameters

datalen

Return Values

TRUE

FALSE

Description

Pointer to memory to store OID structure length.

Description

If valid Structure data type and value is received.

10.15.4.9

ProcessGetBulkVar Function

File

BYTE ProcessGetBulkVar(

BYTE* oidValuePtr,

BYTE* oidLenPtr,

BYTE* successor,

ProcessVariables ( see page 374)() processes the received snmp request pdu for each of the variable binding in the

);

Description

variable binding list to produce a response pdu. Depending on the number of the Max_repetitions for every variable in the list for which Bulk information is expected, ProcessGetBulkVar() is executed. It searches for the next lexicographically ordered successor for of the OID received in the request. For each of the iterations upto max-repetitions, the next leaf node is searched in the MIB to that of the leaf node found in the last iteration, for the corresponding variable binding.

383

10.15 SNMP Microchip TCP/IP Stack Help

Remarks

None.

Preconditions

Parameters

rec oidValuePtr oidLenPtr successor

Return Values

FALSE temp.v[0]

Description

Pointer to SNMP MIB variable object information OID

Pointer to new node OID found in MIB

Oid length

'I'th lexicographic successor to be found value

Description

If no lexicographic successor found

Total number of bytes copied to response packet

Functions

10.15.4.10

ProcessGetNextVar Function

File

BYTE ProcessGetNextVar(

ProcessVariables ( see page 374) is called.

);

Description

This routine reads into the MIB stored with the agent in MPFS2 format. It will search for the first lexicographic successor of the variable binding's name in the incoming GetNextRequest-PDU. If found, the corresponding variable binding's name and value fields in the Response pdu are set to the name and value of the located variable. If the lexicographic succesor is not found, the vlaue filed is set to "endofMibView" and name field is retained as in request.

Remarks

None.

Preconditions

Parameters

rec pduDbPtr

Return Values

Value

FALSE

Description

Pointer to SNMP MIB object information for which next node to be found

Pointer to received pdu information database

Description

Total number of bytes copied to response packet if succesful.

If End of MIB is reached or processing is failure.

384

10.15 SNMP Microchip TCP/IP Stack Help Functions

10.15.4.11

ProcessGetVar Function

File

BYTE ProcessGetVar(

BOOL bAsOID,

);

Description

This routine processes the received snmp Get request pdu for the variable binding in the request and also creates the response pdu.

Remarks

None.

Preconditions

Parameters

rec bAsOID

Return Values

varLen

FALSE

Description

Pointer to SNMP MIB variable object information

Oid flag.

Description

Number of bytes put in response tx pdu

If any of the elements of the request pdu validation fails.

10.15.4.12

ProcessSnmpv3MsgData Function

File

BOOL ProcessSnmpv3MsgData(

);

Description

Once the received pdu is validated as Snmpv3 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.

Remarks

None

Preconditions

The received udp packet is varified as valid SNMPv3 request.

385

10.15 SNMP

Parameters

pduDbPtr

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help

Description

Pointer to received pdu information database

Functions

Description

If the snmp request processing is successful.

If the processing failed else the processing is not completed.

10.15.4.13

SNMPGetExactIndex Function

File

BOOL SNMPGetExactIndex(

SNMP_INDEX index

);

Description

Remarks

Only sequence index needs to be handled in this function.

Preconditions

None

Parameters

var index

Return Values

TRUE

FALSE

Description

Variable id as per mib.h (input)

Index of variable (input)

Description

If the exact index value exists for given variable at given index.

Otherwise.

10.15.4.14

SNMPIdRecrdValidation Function

File

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

386

10.15 SNMP Microchip TCP/IP Stack Help Functions 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.

Remarks

None.

Preconditions

None

Parameters

var oidValuePtr oidLen

Return Values

TRUE

FALSE

Description

Variable rec whose record id need to be validated

OID Value oidValuePtr length

Description

If a Var ID exists .

Otherwise.

10.15.4.15

SNMPIsValidSetLen Function

File

BOOL SNMPIsValidSetLen(

This function will be called for only dynamic variables that are defined as ASCII_STRING and OCTET_STRING ( see page

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.

Remarks

357) (i.e. data length greater than 4 bytes)

Preconditions

ProcessSetVar ( see page 374)() is called.

Parameters

var len index

Return Values

TRUE

FALSE

Description

Variable id whose value is to be set

Length value that is to be validated.

instance of a OID

Description

if given var can be set to given len if otherwise.

387

10.15 SNMP Microchip TCP/IP Stack Help Functions

10.15.4.16

Snmpv3AESDecryptRxedScopedPdu Function

File

BYTE Snmpv3AESDecryptRxedScopedPdu();

Description

This routine decrypts SNMPV3 incoming PDU using AES protocol , but before this encrypted data length is verified.If the length of the encrypted OCTECT-STRING is not multiple of 8, then dryption will be halted. RFC - 3414. ( section 8)

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Return Values

SNMPV3_MSG_PRIV_FAIL

SNMPV3_MSG_PRIV_PASS

Description

Failure

Success

10.15.4.17

Snmpv3AESEncryptResponseScopedPdu Function

File

SNMPV3_RESPONSE_WHOLEMSG* plain_text

BYTE Snmpv3AESEncryptResponseScopedPdu(

);

Description

This routine encrypts SNMPV3 outgoing PDU using AES protocol to maintain the data confidentiality. The data is encrypted in Cipher Block Chaining mode. The length of the encrypted data should be multiple of 8 and it is not then then data is padded in the end if necessary. RFC - 3414. ( section 8)

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

plain_text

Return Values

SNMPV3_MSG_PRIV_FAIL

SNMPV3_MSG_PRIV_PASS

Description

whole PDU message

Description

Failure

Success

388

10.15 SNMP Microchip TCP/IP Stack Help Functions

10.15.4.18

Snmpv3AuthenticateRxedPduForDataIntegrity Function

File

SNMPV3_REQUEST_WHOLEMSG* rxDataPtr

BYTE Snmpv3AuthenticateRxedPduForDataIntegrity(

);

Description

This routine authenticates SNMPV3 incoming report PDU message and also for different type of GET requests with both

MD5 and SHA protocol.If the received PDU username is similar to "initial", then there shoud be report PDU. RFC - 3414.

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

rxDataPtr

Return Values

SNMPV3_MSG_AUTH_PASS

SNMPV3_MSG_AUTH_FAIL

Description

incoming PDU

Description

Authentication ( see page 91) success

Authentication ( see page 91) failure

10.15.4.19

Snmpv3AuthenticateTxPduForDataIntegrity Function

File

SNMPV3_RESPONSE_WHOLEMSG* txDataPtr

BYTE Snmpv3AuthenticateTxPduForDataIntegrity(

);

Description

This routine authenticates SNMPV3 outgoing report PDU message and also for GET Response PDU for whole message.

RFC - 3414.

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

txDataPtr

Description

outgoing PDU

389

10.15 SNMP

Return Values

SNMPV3_MSG_AUTH_PASS

SNMPV3_MSG_AUTH_FAIL

Microchip TCP/IP Stack Help

Description

Authentication ( see page 91) success

Authentication ( see page 91) failure

10.15.4.20

Snmpv3AuthKeyZeroing2HmacBufLen64 Function

File

C void

Snmpv3AuthKeyZeroing2HmacBufLen64(

UINT8* authKey,

UINT8 authKeyLen,

UINT8 hashType

);

Description

this routine will pad the (64-authKeyLen) number of zeros to the end of auth key localized buffer.

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

authkey authKeylen hashType

Description

authentication key buffer authentication key length authentication type

Functions

10.15.4.21

Snmpv3BufferPut Function

File

SNMPV3MSGDATA * putbuf

BOOL Snmpv3BufferPut(

BYTE val,

);

Description

The SNMPv3 stack implementation uses dynamically allocated memory buffer for processing of request and response packets. This routine copies the BYTE data to the allocated buffer and updates the offset length couter.

Remarks

This routine is used by the SNMPv3 stack. If required to be used by the application code, valid pointers should be passed to this routine.

Preconditions

The SNMPv3 stack has sucessfully allocated dynamic memory buffer from the Heap

390

10.15 SNMP

Parameters

val putbuf

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help

Description

BYTE value to be written to the buffer pointer to the dynamically allocated buffer to which the 'val' to be written

Functions

Description

if successfully write to the buffer failure in writing to the buffer

10.15.4.22

Snmpv3CmprTrapSecNameAndSecLvlWithUSMDb

Function

File

STD_BASED_SNMPV3_SECURITY_LEVEL securityLevel

BOOL Snmpv3CmprTrapSecNameAndSecLvlWithUSMDb(

BYTE tragetIndex,

BYTE userTrapSecLen,

UINT8 * userTrapSecurityName,

);

Description

There are two different data base tables defined with SNMPv3 stack, like 'snmpV3UserDataBase ( see page 437)' and

'gSnmpv3TrapConfigData ( see page 429)'. This routine is used to validte the trap user security level setting with SET

request.

Remarks

None.

Preconditions

SET operation would be allowed if the USM security conditions and user security name in the request is matched to one of the user security name stored in the usm user database.

Parameters

userTrapSecLen userTrapSecurityName securityLevel

Return Values

TRUE

FLASE

Description

user sec name length in the SET request pointer to user sec name in the SET request trap security level to be SET on the agent

Description

if the trap target user sec level setting is successful

If the SET failed due to non matching of the security parameters

10.15.4.23

Snmpv3ComputeHMACIpadOpadForAuthLoclzedKey

Function

File

391

10.15 SNMP Microchip TCP/IP Stack Help

C void

Snmpv3ComputeHMACIpadOpadForAuthLoclzedKey(

UINT8 userDBIndex

);

Description

This routine computes HMAC inner and outer pad strings for authorization localized key. RFC - 2104.

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

userDBIndex

Description

password storage poniter

Functions

10.15.4.24

Snmpv3ComputeHmacMD5Digest Function

File

UINT8* Snmpv3ComputeHmacMD5Digest(

UINT8 * inData,

UINT32 dataLen,

UINT8* userExtendedLclzdKeyIpad,

UINT8* userExtendedLclzdKeyOpad

);

Description

This routine supports data origin authentication and data integrity MD5 authentication . Both iPAD and OPAD is used to calculate the authencate digest string. RFC - 3414 ( section 6)

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

digestptr indata dataLen userExtendedLclzdKeyIpad userExtendedLclzdKeyOpad

Return Values

UINT8 *

Description

output string input data input data length

IPAD

OPAD

Description

HMAC MD5 digest string

392

10.15 SNMP Microchip TCP/IP Stack Help Functions

10.15.4.25

Snmpv3ComputeHmacShaDigest Function

File

UINT8* Snmpv3ComputeHmacShaDigest(

UINT8 * inData,

UINT32 dataLen,

UINT8* userExtendedLclzdKeyIpad,

UINT8* userExtendedLclzdKeyOpad

);

Description

This routine supports data origin authentication and data integrity SHA authentication . Both iPAD and OPAD is used to calculate the authencate digest string. RFC - 3414 ( section 6)

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

digestptr indata dataLen userExtendedLclzdKeyIpad userExtendedLclzdKeyOpad

Return Values

UINT8 *

Description

output string input data input data length

IPAD

OPAD

Description

HMAC SHA digest string

10.15.4.26

Snmpv3ComputeMd5HmacCode Function

File

C void

Snmpv3ComputeMd5HmacCode(

UINT8 xx_bits,

UINT8* digestptr,

UINT8 * indata,

UINT32 dataLen,

UINT8* userExtendedLclzdKeyIpad,

UINT8* userExtendedLclzdKeyOpad

);

Description

This routine supports data origin authentication and data integrity MD5 authentication . Both iPAD and OPAD is used to calculate the authencate digest string. RFC - 3414 ( section 6)

Remarks

None

393

10.15 SNMP Microchip TCP/IP Stack Help

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

xx_bits digestptr indata dataLen userExtendedLclzdKeyIpad userExtendedLclzdKeyOpad

Description

96 bit output string input data input data length

IPAD

OPAD

Functions

10.15.4.27

Snmpv3ComputeShaHmacCode Function

File

C void

Snmpv3ComputeShaHmacCode(

UINT8 xx_bits,

UINT8* digestptr,

UINT8 * indata,

UINT32 dataLen,

UINT8* userExtendedLclzdKeyIpad,

UINT8* userExtendedLclzdKeyOpad

);

Description

This routine supports data origin authentication and data integrity SHA authentication . Both iPAD and OPAD is used to calculate the authencate digest string. RFC - 3414 ( section 6)

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

xx_bits digestptr indata dataLen userExtendedLclzdKeyIpad userExtendedLclzdKeyOpad

Description

96 bit output string input data input data length

IPAD

OPAD

10.15.4.28

Snmpv3FormulateEngineID Function

File

Formulates the snmpEngineID ( see page 433) depending on value of 'fifthOctectIdentifier'. as MAC_ADDR_ENGN_ID

C void

Snmpv3FormulateEngineID(

UINT8 fifthOctectIdentifier

394

10.15 SNMP Microchip TCP/IP Stack Help Functions

);

Description

using the application MAC address. 'fifthOctectIdentifier' defualt set to MAC_ADDR_ENGN_ID as the following octets used

for the snmpEngineID ( see page 433) are of mac address.

User can set this octet of their choice to fomulate new

snmpEngineID ( see page 433).

fifthOctectIdentifier=IPV4_ADDR_ENGN_ID;

If fifthOctectIdentifier=ADMIN_ASSIGNED_TEXT; or fifthOctectIdentifier=ADMIN_ASSIGNED_OCTETS; then the following octets should be provided by the administrator through some custom application interface mechanism. API parameter

'fifthOctectIdentifier' has to be upated in the intefrace API before passing through Snmpv3FormulateEngineID().

Remarks

Authentication ( see page 91) and encryption keys are generated using corresponding passwords and snmpEngineID ( see page 433). If the snmpEngineID ( see page 433) is newly configured, then the auth and privacy keys would also change. Hence while using this API to change the snmpEngineID ( see page 433) dynamically, care should be taken to

update the new localized keys at the agent as well as at the manager.

Preconditions

InitAppConfig(); is called.

Parameters

fifthOctectIdentifier

Description

Value of the 5th octet in the snmpEngineID ( see page 433) which indicates

how the rest (6th and following octets) are formatted.

10.15.4.29

Snmpv3FreeDynAllocMem Function

File

C void

Snmpv3FreeDynAllocMem();

Description

On the successful completion of the processing of the SNMPv3 request, or the failure in the processing due to improper

PDU formats, the allocated dynamic memory is required to be freed. This routine calls the free(), to deallocate memory.

Remarks

The SNMPv3 stack does uses the dynamic memory extensively for different processing needs, hence incoming and outgoing pdu memory buffers are created. This routine checks for the memory is being allocated before it attempts for the deallocation.

Preconditions

The dyanmic memory buffer is allocated.

10.15.4.30

Snmpv3GetAuthEngineTime Function

File

'snmpEngineTime ( see page 434)' is used for Timeliness checking for Message level security. Snmp engine keep updating the ''snmpEngineTime ( see page 434)' variable for checking the time window for the requrest and

C void

Snmpv3GetAuthEngineTime();

395

10.15 SNMP Microchip TCP/IP Stack Help Functions

Description

responses/inform etc. This routine also updates snmpEngineBoots ( see page 433) in scenarios of internal timer reset or

'snmpEngineTime ( see page 434)' cntr ovrflowed the (2^31 -1) value specified in RFC3411.

Remarks

This routine is called every time the rx/tx PDU processing is handled by the SNMP agent. Updates the 'snmpEngineTime ( see page 434)' and requires frequnet access to internal timer registers.

Preconditions

SNMPInit ( see page 376)(); is called.

10.15.4.31

Snmpv3GetBufferData Function

File

SNMPV3MSGDATA getbuf,

BYTE Snmpv3GetBufferData(

UINT16 pos

);

Description

The SNMPv3 stack implementation uses dynamically allocated memory buffer for processing of request and response packets. This routine reads the BYTE data from the allocated buffer at the positions (offset) provided.

Remarks

The read position offset is required to be provided every time the routine is called. This API do not increment the buffer read offset automatically, everytime it is called.

Preconditions

The SNMPv3 stack has sucessfully allocated dynamic memory buffer from the Heap

Parameters

getbuf pos

Return Values

BYTE

Description

Structure from where to read the data byte.

position in the buffer from which the data to be read

Description

1 byte value read

10.15.4.32

Snmpv3GetSecurityLevel Function

File

Only Privacy and Authentication ( see page 91)

BYTE Snmpv3GetSecurityLevel(

BYTE userIndex

);

396

10.15 SNMP Microchip TCP/IP Stack Help Functions

Description

This routine uses authenticationa dn privacy type to find out the exact security enum type.

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Return Values

NO_REPORT_PRIVACY_AND_AUTH_PROVIDED

Description

NO_REPORT_NO_PRIVACY_BUT_AUTH_PROVIDED Only Auth , no privacy and no report

NO_REPORT_NO_PRIVACY_NO_AUTH

No report, no Privacy and no Authentication ( see page 91)

10.15.4.33

Snmpv3GetTrapSecurityLevel Function

File

STD_BASED_SNMPV3_SECURITY_LEVEL securityLevel

BYTE Snmpv3GetTrapSecurityLevel(

);

Description

This routine to find the report, auth and privacy flags setting for the trap to be generated. The message flags octet's least significant three bits: Reportable, PrivFlag, AuthFlag forms different secuity level combinations.

Remarks

None.

Preconditions

None

Return Values

NO_REPORT_NO_PRIVACY_NO_AUTH

Description

No authentication, no encryption

NO_REPORT_NO_PRIVACY_BUT_AUTH_PROVIDED authentication but no encryption

NO_REPORT_PRIVACY_AND_AUTH_PROVIDED authentication and encryption

INVALID_MSG if security level doesn't match any of the above

10.15.4.34

Snmpv3Init Function

File

At least one UDP socket must be available. UDPInit ( see page 627)() is already called.

C void

Snmpv3Init();

Description

This routine will intialize SNMPv3 global data base ,engine ID and USM

397

10.15 SNMP Microchip TCP/IP Stack Help

Remarks

None

Preconditions

Functions

10.15.4.35

Snmpv3InitializeUserDataBase Function

File

C void

Snmpv3InitializeUserDataBase();

Description

There are three default username, authentication, authenticaton password and Privacy name and privacy password intialized with SNMPv3 global databse.

Remarks

None

Preconditions

SNMPv3Init() is called.

10.15.4.36

Snmpv3IsValidAuthStructure Function

File

This routine is used to verify whether the received varbind is of type STRUCTURE ( see page 366) and to find out the

BYTE Snmpv3IsValidAuthStructure(

WORD* dataLen

);

Description

variable binding structure length.

Remarks

None.

Preconditions

If variable data structure is not type STRUCTURE ( see page 366).

Parameters

datalen

Return Values

headrbytes

FALSE

Description

Pointer to memory to store OID structure length.

Description

Variable binding length.

398

10.15 SNMP Microchip TCP/IP Stack Help Functions

10.15.4.37

Snmpv3IsValidInt Function

File

This routine populates and validates the received variable for the data type as "ASN_INT ( see page 349)" and the data

BOOL Snmpv3IsValidInt(

DWORD* val

);

Description

length for max 4 bytes. This rotuine only refers to the incoming snmpv3 request dynamically allocated memory buffer

'gSNMPv3ScopedPduRequestBuf ( see page 428)' .

Remarks

None.

Preconditions

None

Parameters

val

ReturnValues

FALSE

Description

Pointer to memory where int var value will be stored.

TRUE - If valid integer type and value is received.

Other than integer data type and value received .

10.15.4.38

Snmpv3MsgProcessingModelProcessPDU Function

File

SNMP_ERR_STATUS Snmpv3MsgProcessingModelProcessPDU(

BYTE inOutPdu

);

Description

The recievd SNMPv3 PDU or the transmit PDU header has message processing data bytes infomration. This routine retrievs the messgae processing model infomration from the stored pdu or write the appropriate msg proc info to the repsonse msg buffer.

Remarks

The messgae processing model parameters like 'msgID', 'msgMaxSize', 'msgFlags' and 'msgSecurityModel' decides the

SNMPv3 engine processing modalities regarding request or response PDU

Preconditions

Valid SNMPv3 request msg is received.

Parameters

inOutPdu

Description

indicates whether the incomig PDU is to be read for msg proc values to be retrieved or the response PDU is to be populated with these values

399

10.15 SNMP

Return Values

SNMP_NO_CREATION

SNMP_NO_ERR

Microchip TCP/IP Stack Help Functions

Description

Failure due to improper msg processing information format in the received PDU or failure in constructing the response PDU.

The message processing infomration retrieval or response PDU fomration is successful

10.15.4.39

Snmpv3Notify Function

File

BOOL Snmpv3Notify(

'gSnmpv3TrapConfigData ( see page 429)' table's security user name for

UINT8 targetIndex

);

Description

This function creates SNMPv3 trap PDU and sends it to previously specified remoteHost.

Remarks

None

Preconditions

TRAP event is triggered.

Parameters

var val index

Description

SNMP var ID that is to be used in notification

Value of var. Only value of BYTE, WORD or DWORD can be sent.

Index of var. If this var is a single,index would be 0, or else if this var Is a sequence, index could be any value from 0 to 127 targetIndex -index of the

which the TRAP PDU message header to constructed.

Return Values

TRUE

FALSE

This would fail under following contions

4) Data type of given var is unknown

SNMPV3_MSG_AUTH_FAIL

Description

if SNMP notification was successful sent. This does not guarantee that remoteHost recieved it.

Notification sent failed.

1) Given SNMP_BIB_FILE does not exist in MPFS 2) Given var does not exist.

3) Previously given agentID does not exist only possible if MPFS itself was corrupted. SNMPV3_MSG_PRIV_FAIL

-encryption of the trap msg failed

HAMC of the trap msg failed

10.15.4.40

Snmpv3Pswd2LocalizedAuthKeyMD5Hashing Function

File

400

10.15 SNMP Microchip TCP/IP Stack Help

C void

Snmpv3Pswd2LocalizedAuthKeyMD5Hashing(

UINT8* pswdToLocalized,

UINT8 pswdLen

);

Description

This routine converts HMAC-MD5 authentication password key to localized key using snmpSngineID(RFC- 3414).

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

pswdToLocalized pswdLen

Description

password storage poniter password length.

Functions

10.15.4.41

Snmpv3Pswd2LocalizedAuthKeySHAHashing Function

File

C void

Snmpv3Pswd2LocalizedAuthKeySHAHashing(

UINT8* pswdToLocalized,

UINT8 pswdLen

);

Description

This routine converts HMAC-SHA authentication password key to localized key using snmpSngineID(RFC- 3414).

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

pswdToLocalized pswdLen

Description

password storage poniter password length.

10.15.4.42

Snmpv3ReportPdu Function

File

SNMPV3MSGDATA * dynScopedBufPtr

C void

Snmpv3ReportPdu(

);

401

10.15 SNMP Microchip TCP/IP Stack Help Functions

Description

The SNMPv3 PDU exchange starts with the agent sending a report pdu on reception of any Get_Request PDU for SNMPv3 request. This routine froms the report pdu for response to the requesting entity.

Remarks

None.

Preconditions

ProcessVariables ( see page 374)() is called and a valid SNMPv3 request is received.

Parameters

dynScopedBufPtr

Description

pointer to the response buffer memory where the 'report' response to be savced for transmission.

10.15.4.43

Snmpv3ScopedPduProcessing Function

File

SNMP_ERR_STATUS Snmpv3ScopedPduProcessing(

BYTE inOutPdu

);

Description

The recievd SNMPv3 PDU or the transmit PDU header has scoped pdu parameters like 'contextEngineID' 'context name' etc. This routine retrievs these parameters infomration from the stored incoming pdu or write the appropriate dynamically allocated memory for the transmit response PDU.

Remarks

The scoped pDu parameters msg data : - [==

Preconditions

Valid SNMPv3 request msg is received.

Parameters

inOutPdu

Description

indicates whether the incomig PDU is to be read for scoped pdu paraemters to be retrieved or the response PDU to be populated with these values

Return Values

SNMP_NO_CREATION

SNMP_NO_ERR

Description

Failure due to improper scoped pdu information format in the PDU or failure in constructing the response PDU.

The scoped parameters retrieval or response PDU fomration is successful

10.15.4.44

Snmpv3SetErrorStatus Function

File

SNMP_ERR_STATUS errorStatus,

C void

Snmpv3SetErrorStatus(

WORD errorStatusOffset,

402

10.15 SNMP Microchip TCP/IP Stack Help Functions

WORD errorIndexOffset,

BYTE errorIndex,

SNMPV3MSGDATA * dynScopedPduPutBuf

);

Returns

None.

Description

This routine processes the received snmp Get request pdu for the variable binding in the request and also creates the response pdu.

Remarks

None.

Preconditions

Parameters

errorStatusOffset errorIndexOffset errorStatus errorIndex dynScopedPduPutBuf

Description

Offset to update error status in Response Tx pdu

Offset to update error index

Snmp process error to be updated in response.

Index of the request varbind in the var bind list for which error status is to be updated.

dynamic snmpv3 scoped pdu buffer

10.15.4.45

Snmpv3TrapScopedpdu Function

File

UINT8 Snmpv3TrapScopedpdu(

the 'gSnmpv3TrapConfigData ( see page 429)' table's security user name for

UINT8 targetIndex

);

Description

This routine forms the trap scoped pdu header for the SNMPv3 trap PDU to be originated from this agent. Scoped pdu comprises of msg data : - [== For ASCII STR trap VAL(argument) contains the pointer address of the string variable.

Remarks

None.

Preconditions

TRAP event is triggered.

Parameters

var val index

Description

var id of the variable whose value to be sent in the trap pdu value of the variable index of the variable in the multiple variable bind scenario targetIndex -index of

which the TRAP PDU message header to constructed.

403

10.15 SNMP

Return Values

TRUE

Microchip TCP/IP Stack Help Functions

Description

The trap scoped pdu header generation is successful. FALSE -The trap scoped pdu header generation failed.

10.15.4.46

Snmpv3UserSecurityModelProcessPDU Function

File

SNMP_ERR_STATUS Snmpv3UserSecurityModelProcessPDU(

BYTE inOutPdu

);

Description

The recievd SNMPv3 PDU or the transmit PDU header has message security data bytes infomration. This routine retrievs the messgae security parameters infomration from the stored incoming pdu or write the appropriate security model info to the repsonse msg buffer.

Remarks

The user security parameter constitute the vital information for the message authentication and privacy of the message. The user security model parameters header structure MsgAuthEngnID+MsgAuthEngnBoots+MsgAuthEngnTime

+MsgUserName+MsgAuthParam+MsgPrivParam

Preconditions

Valid SNMPv3 request msg is received.

Parameters

inOutPdu

Description

indicates whether the incomig PDU is to be read for user security model to be retrieved or the response PDU to be populated with these values

Return Values

SNMP_NO_CREATION

SNMP_NO_ERR

Description

Failure due to improper security model processing information format in the received PDU or failure in constructing the response PDU.

The user security model retrieval or response PDU fomration is successful

10.15.4.47

Snmpv3UsmAesEncryptDecryptInitVector Function

File

The IV is concatenated as : the 32-bit snmpEngineBoots ( see page 433) is converted to the first 4 Octects and the

C void

Snmpv3UsmAesEncryptDecryptInitVector(

BYTE inOutPdu

);

Description

snmpEngineTime ( see page 434) converted to subsequent four bytes.

Remarks

None

404

10.15 SNMP Microchip TCP/IP Stack Help

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

inOutPdu

Description

SNMP request PDU

10.15.4.48

Snmpv3UsmOutMsgAuthenticationParam Function

File

C void

Snmpv3UsmOutMsgAuthenticationParam(

UINT8 hashType

);

Description

This routine prepares out message with HMAC-MD5 or HMAC-SHA1 authentication protocol.(RFC- 3414 - section 6)

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

hashType

Description

authentication protocol type

10.15.4.49

Snmpv3USMOutMsgPrivParam Function

File

C void

Snmpv3USMOutMsgPrivParam();

Description

SNMPEngineTime is used to encrypt the outgoing message with a random value.

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Functions

10.15.4.50

Snmpv3UsmSnmpEngnAuthPrivPswdLocalization

Function

File

405

10.15 SNMP Microchip TCP/IP Stack Help Functions

C void

Snmpv3UsmSnmpEngnAuthPrivPswdLocalization(

UINT8 userDBIndex

);

Description

This routine converts MD5 or SHA1 and AES privacy password key to localized key using snmpSngineID(RFC- 3414 section 6).

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Parameters

userDBIndex

Description

authentication protocol type

10.15.4.51

Snmpv3ValidateEngineId Function

File

BOOL Snmpv3ValidateEngineId();

Description

This routine validates Engine ID.

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Return Values

FALSE

TRUE

Description

Failure

Success

10.15.4.52

Snmpv3ValidateSecNameAndSecLvl Function

File

BOOL Snmpv3ValidateSecNameAndSecLvl();

Description

This routine validates secuirity name and secuirty level with SNMP global data base for an incoming PDU.

Remarks

None

406

10.15 SNMP Microchip TCP/IP Stack Help

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Return Values

TRUE

FALSE

Description

success failure

10.15.4.53

Snmpv3ValidateSecurityName Function

File

BOOL Snmpv3ValidateSecurityName();

Description

This routine validates user name.

Remarks

None

Preconditions

SNMPv3Init() and ProcessVariabels() are called.

Return Values

FALSE

TRUE

Description

Failure

Success

Structs, Records, Enums

10.15.5

Structs, Records, Enums

Module

AccessCtrlSubSysIsAccessAllowed ( see page 408)

Structures

Name

Description

Applications are the typical clients of the service(s) of the Access

Control Subsystem. The following primitive is provided by the

Access Control Subsystem to check if access is allowed:

statusInformation ( see page 422) = -- success or errorIndication

dispatcherProcessPdu ( see page 409) Process Incoming Request or Notification PDU

Dispatcher provides the following primitive to pass an incoming snmp pdu to an application.

dispatcherStatusInfo ( see page 409)

Generate Outgoing Request or Notification

statusInformation ( see page 422) = -- sendPduHandle if success --

errorIndication if failure

dispathcerReturnResponsePdu ( see page 410)

Generate Outgoing Response

The PDU Dispatcher provides the following primitive for an application to return an SNMP Response PDU to the PDU

Dispatcher: result = SUCCESS or FAILURE

407

10.15 SNMP Microchip TCP/IP Stack Help Structs, Records, Enums

MsgProcModPrepareDataElements ( see page 411)

Prepare Data Elements from an Incoming SNMP Message

The Message Processing Subsystem provides this service primitive for preparing the abstract data elements from an incoming SNMP message: result = -- SUCCESS or errorIndication

MsgProcModPrepareOutgoingMessage

MsgProcModPrepareResponseMessage

Prepare Outgoing SNMP Request or Notification Message

The Message Processing Subsystem provides this service primitive for preparing an outgoing SNMP Request or Notification Message

processResponsePdu ( see page 413) Process Incoming Response PDU

Prepare an Outgoing SNMP Response Message

The Message Processing Subsystem provides this service primitive for preparing an outgoing SNMP Response Message: result = --

SUCCESS or FAILURE

The PDU Dispatcher provides the following primitive to pass an incoming SNMP Response PDU to an application: success or errorIndication

registerContextEngineID ( see page

SecuritySysGenerateRequestMsg ( see page 414)

SecuritySysGenerateResponseMsg ( see page 415)

This is record SecuritySysGenerateRequestMsg.

Generate a Response Message

The Security Subsystem provides the following primitive to generate a Response message:

StateRelease ( see page 415)

unregisterContextEngineID ( see page

416)

Release State Reference Information

All Subsystems which pass stateReference information also provide a primitive to release the memory that holds the referenced state information

This is record unregisterContextEngineID.

10.15.5.1

AccessCtrlSubSysIsAccessAllowed Structure

File

statusInformation ( see page 422) = -- success or errorIndication

C struct

AccessCtrlSubSysIsAccessAllowed {

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE viewType;

BYTE* contextName;

BYTE* variableName;

};

Members

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE viewType;

BYTE* contextName;

BYTE* variableName;

Description

Security Model in use principal who wants to access

Level of Security read, write, or notify view context containing variableName

OID for the managed object

Description

Applications are the typical clients of the service(s) of the Access Control Subsystem. The following primitive is provided by the Access Control Subsystem to check if access is allowed:

408

10.15 SNMP Microchip TCP/IP Stack Help Structs, Records, Enums

10.15.5.2

dispatcherProcessPdu Structure

File

C struct

dispatcherProcessPdu {

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

DWORD_VAL maxSizeResponseScopedPDU;

UINT32 stateReference;

};

Members

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

DWORD_VAL maxSizeResponseScopedPDU;

UINT32 stateReference;

Description

typically, SNMP version

Security Model in use on behalf of this principal

Level of Security data from/at this SNMP entity data from/in this context the version of the PDU

SNMP Protocol Data Unit maximum size of the Response PDU reference to state information needed when sending a response

Description

Process Incoming Request or Notification PDU

Dispatcher provides the following primitive to pass an incoming snmp pdu to an application.

10.15.5.3

dispatcherStatusInfo Structure

File

statusInformation ( see page 422) = -- sendPduHandle if success -- errorIndication if failure

C struct

dispatcherStatusInfo {

BYTE transportDomain;

UINT32 transportAddress;

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

BOOL expectResponse;

};

409

10.15 SNMP Microchip TCP/IP Stack Help

Members

BYTE transportDomain;

UINT32 transportAddress;

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

BOOL expectResponse;

Description

transport domain to be used transport address to be used typically, SNMP version

Security Model to use on behalf of this principal

Level of Security requested data from/at this entity data from/in this context the version of the PDU

SNMP Protocol Data Unit

TRUE or FALSE

Description

Generate Outgoing Request or Notification

Structs, Records, Enums

10.15.5.4

dispathcerReturnResponsePdu Structure

File

C struct

dispathcerReturnResponsePdu {

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

UINT32 maxSizeResponseScopedPDU;

UINT32 stateReference;

maximum size sender can accept ( see page 174)

};

Members

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

Description

typically, SNMP version

Security Model in use on behalf of this principal same as on incoming request

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion; data from/at this SNMP entity data from/in this context the version of the PDU

BYTE* PDU; SNMP Protocol Data Unit

UINT32 maxSizeResponseScopedPDU;

UINT32 stateReference; statusInformation statInfo; reference to state information as presented with the request success or errorIndication, error counter OID/value if error

410

10.15 SNMP Microchip TCP/IP Stack Help Structs, Records, Enums

Description

Generate Outgoing Response

The PDU Dispatcher provides the following primitive for an application to return an SNMP Response PDU to the PDU

Dispatcher: result = SUCCESS or FAILURE

10.15.5.5

MsgProcModPrepareDataElements Structure

File

C struct

MsgProcModPrepareDataElements {

BYTE transportDomain;

UINT32 transportAddress;

BYTE* wholeMsg;

UINT32 wholeMsgLength;

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

BYTE pduType;

UINT32 maxSizeResponseScopedPDU;

maximum size sender can accept ( see page 174)

UINT32 stateReference;

};

Members

BYTE transportDomain;

UINT32 transportAddress;

BYTE* wholeMsg;

UINT32 wholeMsgLength;

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

Description

origin transport domain origin transport address as received from the network as received from the network typically, SNMP version

Security Model to use on behalf of this principal

Level of Security requested

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion; data from/at this entity data from/in this context the version of the PDU

BYTE* PDU;

BYTE pduType;

SNMP Protocol Data Unit

SNMP PDU type OUT sendPduHandle; // handle for matched request

UINT32 maxSizeResponseScopedPDU;

statusInformation statInfo;

UINT32 stateReference; success or errorIndication error counter OID/value if error reference to state information to be used for possible Response

Description

Prepare Data Elements from an Incoming SNMP Message

The Message Processing Subsystem provides this service primitive for preparing the abstract data elements from an incoming SNMP message: result = -- SUCCESS or errorIndication

411

10.15 SNMP Microchip TCP/IP Stack Help Structs, Records, Enums

10.15.5.6

MsgProcModPrepareOutgoingMessage Structure

File

C struct

MsgProcModPrepareOutgoingMessage {

BYTE transportDomain;

UINT32 transportAddress;

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

BOOL expectResponse;

BYTE destTransportDomain;

UINT32 destTransportAddress;

BYTE* outgoingMessage;

UINT32 outgoingMessageLength;

};

Members

BYTE transportDomain;

UINT32 transportAddress;

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

BOOL expectResponse;

BYTE destTransportDomain;

UINT32 destTransportAddress;

BYTE* outgoingMessage;

UINT32 outgoingMessageLength;

Description

transport domain to be used transport address to be used typically, SNMP version

Security Model to use on behalf of this principal

Level of Security requested data from/at this entity data from/in this context the version of the PDU

SNMP Protocol Data Unit

TRUE or FALSE IN sendPduHandle; //the handle for matching incoming responses destination transport domain destination transport address the message to send its length

Description

Prepare Outgoing SNMP Request or Notification Message

The Message Processing Subsystem provides this service primitive for preparing an outgoing SNMP Request or Notification

Message

10.15.5.7

MsgProcModPrepareResponseMessage Structure

File

412

10.15 SNMP Microchip TCP/IP Stack Help Structs, Records, Enums

C struct

MsgProcModPrepareResponseMessage {

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

UINT32 maxSizeResponseScopedPDU;

UINT32 stateReference;

maximum size able to accept ( see page 174)

BYTE destTransportDomain;

UINT32 destTransportAddress;

BYTE* outgoingMessage;

UINT32 outgoingMessageLength;

};

Members

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

Description

typically, SNMP version same as on incoming request same as on incoming request same as on incoming request

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU; data from/at this SNMP entity data from/in this context the version of the PDU

SNMP Protocol Data Unit

UINT32 maxSizeResponseScopedPDU;

UINT32 stateReference; reference to state information as presented with the request statusInformation statInfo; success or errorIndication, error counter OID/value if error

BYTE destTransportDomain;

UINT32 destTransportAddress;

BYTE* outgoingMessage;

UINT32 outgoingMessageLength; destination transport domain destination transport address the message to send its length

Description

Prepare an Outgoing SNMP Response Message

The Message Processing Subsystem provides this service primitive for preparing an outgoing SNMP Response Message: result = -- SUCCESS or FAILURE

10.15.5.8

processResponsePdu Structure

File

C struct

processResponsePdu {

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU;

413

10.15 SNMP Microchip TCP/IP Stack Help Structs, Records, Enums

};

Members

BYTE messageProcessingModel;

BYTE securityModel;

BYTE* securityName;

BYTE securityLevel;

BYTE* contextEngineID;

BYTE* contextName;

BYTE pduVersion;

BYTE* PDU; statusInformation statInfo;

Description

Process Incoming Response PDU

Description

typically, SNMP version

Security Model in use on behalf of this principal

Level of Security data from/at this SNMP entity data from/in this context the version of the PDU

SNMP Protocol Data Unit success or errorIndication IN sendPduHandle; //handle from sendPdu

The PDU Dispatcher provides the following primitive to pass an incoming SNMP Response PDU to an application:

10.15.5.9

SecuritySysGenerateRequestMsg Structure

File

C struct

SecuritySysGenerateRequestMsg {

BYTE messageProcessingModel;

BYTE* globalData;

UINT32 maxMessageSize;

BYTE securityModel;

BYTE* securityEngineID;

BYTE* securityName;

BYTE securityLevel;

BYTE* scopedPDU;

BYTE* wholeMsg;

UINT32 wholeMsgLength;

};

Members

BYTE messageProcessingModel;

BYTE* globalData;

UINT32 maxMessageSize;

BYTE securityModel;

BYTE* securityEngineID;

BYTE* securityName;

BYTE securityLevel;

BYTE* scopedPDU;

BYTE* wholeMsg;

UINT32 wholeMsgLength;

Description

typically, SNMP version message header, admin data of the sending SNMP entity for the outgoing message authoritative SNMP entity on behalf of this principal

Level of Security requested message (plaintext) payload OUT securityParameters; //filled in by Security

Module complete generated message length of the generated message

Description

This is record SecuritySysGenerateRequestMsg.

414

10.15 SNMP Microchip TCP/IP Stack Help Structs, Records, Enums

10.15.5.10

SecuritySysGenerateResponseMsg Structure

File

C struct

SecuritySysGenerateResponseMsg {

BYTE messageProcessingModel;

BYTE* globalData;

UINT32 maxMessageSize;

BYTE securityModel;

BYTE* securityEngineID;

BYTE* securityName;

BYTE securityLevel;

BYTE* scopedPDU;

BYTE* wholeMsg;

UINT32 wholeMsgLength;

};

Members

BYTE messageProcessingModel;

BYTE* globalData;

UINT32 maxMessageSize;

BYTE securityModel;

BYTE* securityEngineID;

BYTE* securityName;

BYTE securityLevel;

BYTE* scopedPDU;

Description

typically, SNMP version message header, admin data of the sending SNMP entity for the outgoing message authoritative SNMP entity on behalf of this principal for the outgoing message message (plaintext) payload IN securityStateReference; //reference to security state information from original request OUT securityParameters; //filled in by

Security Module complete generated message length of the generated message

BYTE* wholeMsg;

UINT32 wholeMsgLength;

Description

Generate a Response Message

The Security Subsystem provides the following primitive to generate a Response message:

10.15.5.11

StateRelease Structure

File

C struct

StateRelease {

UINT32 stateReference;

};

Members

UINT32 stateReference;

Description

Release State Reference Information

Description

handle of reference to be released

415

10.15 SNMP Microchip TCP/IP Stack Help Types

All Subsystems which pass stateReference information also provide a primitive to release the memory that holds the referenced state information

10.15.5.12

unregisterContextEngineID Structure

File

INOUT_SNMP_PDU ( see page 417)

C struct

unregisterContextEngineID {

BYTE* contextEngineID;

BYTE pduType;

};

Members

BYTE* contextEngineID;

BYTE pduType;

Description

This is record unregisterContextEngineID.

Description

give up responsibility for this one the pduType(s) to be unregistered

10.15.6

Types

Enumerations

Name

REPORT_FLAG_AND_SECURITY_LEVEL_FLAGS ( see page 417)

SNMP_ENGNID_OCTET_IDENTIFIER_VAL ( see page

419)

SNMPV3_HMAC_HASH_TYPE ( see page 419)

SNMPV3_MSG_AUTH_SEC_PARAM_RESULT ( see page 420)

SNMPV3_MSG_PRIV_SEC_PARAM_RESULT ( see page 420)

SNMPV3_PRIV_PROT_TYPE ( see page 420)

Description

This is type INOUT_SNMP_PDU.

This is type

REPORT_FLAG_AND_SECURITY_LEVEL_FLAG

The fifth octet indicates how the rest (6th and following octets) are formatted. Refer to RFC3411 section5 Page# 41

Type of hash being calculated

This is type

SNMPV3_MSG_AUTH_SEC_PARAM_RESULT.

This is type

SNMPV3_MSG_PRIV_SEC_PARAM_RESULT.

This is type SNMPV3_PRIV_PROT_TYPE.

STD_BASED_SNMP_MESSAGE_PROCESSING_MODEL

( see page 423)

This is type

STD_BASED_SNMP_MESSAGE_PROCESSING

_MODEL.

STD_BASED_SNMP_SECURITY_MODEL ( see page

STD_BASED_SNMPV3_SECURITY_LEVEL ( see page

Snmp Message Processing Model

USM_SECURITY_LEVEL ( see page 424)

This is type

STD_BASED_SNMPV3_SECURITY_LEVEL.

This is type USM_SECURITY_LEVEL.

Module

SecuritySysProcessIncomingMsg ( see page 418)

416

10.15 SNMP

Structures

Microchip TCP/IP Stack Help

Name

SNMPNONMIBRECDINFO ( see page 419)

SNMPV3_REQUEST_WHOLEMSG

( see page 421)

Description

This is type SecuritySysProcessIncomingMsg.

This is type SNMPNONMIBRECDINFO.

This is type SNMPV3_REQUEST_WHOLEMSG.

SNMPV3_RESPONSE_WHOLEMSG

( see page 421)

This is type SNMPV3_RESPONSE_WHOLEMSG.

This is type snmpV3EngnUserDataBase.

snmpV3EngnUserDataBase ( see page 421)

SNMPV3MSGDATA ( see page

snmpV3TrapConfigDataBase ( see page 422)

SNMPv3

snmpv3 target configuration with respect to trap.

statusInformation ( see page 422)

success or errorIndication

10.15.6.1

INOUT_SNMP_PDU Enumeration

File

C typedef enum

{

SNMP_RESPONSE_PDU = 0x01,

SNMP_REQUEST_PDU = 0x02

} INOUT_SNMP_PDU;

Description

This is type INOUT_SNMP_PDU.

10.15.6.2

REPORT_FLAG_AND_SECURITY_LEVEL_FLAGS

Enumeration

File

C typedef enum

{

NO_REPORT_NO_PRIVACY_NO_AUTH = 0x00,

NO_REPORT_NO_PRIVACY_BUT_AUTH_PROVIDED = 0x01,

NO_REPORT_PRIVACY_PROVIDED_BUT_NO_AUTH = 0x02,

NO_REPORT_PRIVACY_AND_AUTH_PROVIDED = 0x03,

REPORT2REQ_NO_PRIVACY_NO_AUTH = 0x04,

REPORT2REQ_NO_PRIVACY_BUT_AUTH_PROVIDED = 0x05,

REPORT2REQ_PRIVACY_PROVIDED_BUT_NO_AUTH = 0x06,

REPORT2REQ_PRIVACY_AND_AUTH_PROVIDED = 0x07,

INVALID_MSG = 0xFF

} REPORT_FLAG_AND_SECURITY_LEVEL_FLAGS;

Members

NO_REPORT_NO_PRIVACY_NO_AUTH = 0x00

Description

00000000b

Types

417

10.15 SNMP Microchip TCP/IP Stack Help

NO_REPORT_NO_PRIVACY_BUT_AUTH_PROVIDED

= 0x01

NO_REPORT_PRIVACY_PROVIDED_BUT_NO_AUTH

= 0x02

NO_REPORT_PRIVACY_AND_AUTH_PROVIDED =

0x03

00000001b

00000010b Priv without Auth is not allowed

00000011b

REPORT2REQ_NO_PRIVACY_NO_AUTH = 0x04 00000100b

REPORT2REQ_NO_PRIVACY_BUT_AUTH_PROVIDED

= 0x05

00000101b

REPORT2REQ_PRIVACY_PROVIDED_BUT_NO_AUTH

= 0x06

00000110b Priv without Auth is not allowed

REPORT2REQ_PRIVACY_AND_AUTH_PROVIDED =

0x07

00000111b

Description

This is type REPORT_FLAG_AND_SECURITY_LEVEL_FLAGS.

Types

10.15.6.3

SecuritySysProcessIncomingMsg Structure

File

C typedef struct

{

UINT32 maxMessageSize;

UINT32 wholeMsgLength;

BYTE* wholeMsg;

BYTE* securityEngineID;

BYTE* securityName;

BYTE* scopedPDU;

UINT32 maxSizeResponseScopedPDU;

BYTE messageProcessingModel;

BYTE securityModel;

BYTE securityLevel;

UINT8 securityEngineIDLen;

BYTE securityNameLength;

} SecuritySysProcessIncomingMsg;

Members

UINT32 maxMessageSize;

UINT32 wholeMsgLength;

BYTE* wholeMsg;

Description

of the sending SNMP entity IN securityParameters; //for the received message length as received on the wire as received on the wire

BYTE* securityEngineID;

BYTE* securityName; authoritative SNMP entity identification of the principal

BYTE* scopedPDU; message (plaintext) payload OUT securityStateReference; //reference to security state

UINT32 maxSizeResponseScopedPDU; maximum size sender can handle

BYTE messageProcessingModel;

BYTE securityModel;

BYTE securityLevel;

UINT8 securityEngineIDLen; typically, SNMP version for the received message

Level of Security authoritative SNMP entity

Description

This is type SecuritySysProcessIncomingMsg.

418

10.15 SNMP Microchip TCP/IP Stack Help Types

10.15.6.4

SNMP_ENGNID_OCTET_IDENTIFIER_VAL Enumeration

File

C typedef enum

{

RESERVED = 0x0,

IPV4_ADDR_ENGN_ID = 0x01,

IPV6_ADDR_ENGN_ID = 0x02,

MAC_ADDR_ENGN_ID = 0x03,

ADMIN_ASSIGNED_TEXT = 0x04,

ADMIN_ASSIGNED_OCTETS = 0x05,

RESERVED_UNUSED = 0x06,

ENTERPRISE_DEFINED = 128

} SNMP_ENGNID_OCTET_IDENTIFIER_VAL;

Members

IPV4_ADDR_ENGN_ID = 0x01

IPV6_ADDR_ENGN_ID = 0x02

MAC_ADDR_ENGN_ID = 0x03

RESERVED_UNUSED = 0x06

ENTERPRISE_DEFINED = 128

Description

4octets

16 octets

6 octets

6 to 127 are reserved and unused

128 to 255 as defiend by the enterprise maximum remaining length

Description

The fifth octet indicates how the rest (6th and following octets) are formatted. Refer to RFC3411 section5 Page# 41

10.15.6.5

SNMPNONMIBRECDINFO Structure

File

C typedef struct

{

UINT8 oidstr[16];

UINT8 version;

} SNMPNONMIBRECDINFO;

Description

This is type SNMPNONMIBRECDINFO.

10.15.6.6

SNMPV3_HMAC_HASH_TYPE Enumeration

File

C typedef enum

{

SNMPV3_HAMC_MD5 = 0u,

SNMPV3_HMAC_SHA1,

SNMPV3_NO_HMAC_AUTH

} SNMPV3_HMAC_HASH_TYPE;

419

10.15 SNMP

Members

SNMPV3_HAMC_MD5 = 0u

SNMPV3_HMAC_SHA1

Description

Type of hash being calculated

Microchip TCP/IP Stack Help

Description

MD5 is being calculated

SHA-1 is being calculated

10.15.6.7

SNMPV3_MSG_AUTH_SEC_PARAM_RESULT

Enumeration

File

C typedef enum

{

SNMPV3_MSG_AUTH_FAIL = 0x00,

SNMPV3_MSG_AUTH_PASS = 0x01

} SNMPV3_MSG_AUTH_SEC_PARAM_RESULT;

Description

This is type SNMPV3_MSG_AUTH_SEC_PARAM_RESULT.

10.15.6.8

SNMPV3_MSG_PRIV_SEC_PARAM_RESULT

Enumeration

File

C typedef enum

{

SNMPV3_MSG_PRIV_FAIL = 0x00,

SNMPV3_MSG_PRIV_PASS = 0x01

} SNMPV3_MSG_PRIV_SEC_PARAM_RESULT;

Description

This is type SNMPV3_MSG_PRIV_SEC_PARAM_RESULT.

10.15.6.9

SNMPV3_PRIV_PROT_TYPE Enumeration

File

C typedef enum

{

SNMPV3_DES_PRIV = 0x0,

SNMPV3_AES_PRIV,

SNMPV3_NO_PRIV

} SNMPV3_PRIV_PROT_TYPE;

Description

This is type SNMPV3_PRIV_PROT_TYPE.

Types

420

10.15 SNMP Microchip TCP/IP Stack Help

10.15.6.10

SNMPV3_REQUEST_WHOLEMSG Structure

File

C typedef struct

{

UINT8* wholeMsgHead;

UINT8* snmpMsgHead;

WORD_VAL wholeMsgLen;

WORD_VAL snmpMsgLen;

WORD msgAuthParamOffsetInWholeMsg;

WORD scopedPduOffset;

BYTE scopedPduAuthStructVal;

WORD scopedPduStructLen;

} SNMPV3_REQUEST_WHOLEMSG;

Description

This is type SNMPV3_REQUEST_WHOLEMSG.

10.15.6.11

SNMPV3_RESPONSE_WHOLEMSG Structure

File

C typedef struct

{

UINT8* wholeMsgHead;

UINT8* snmpMsgHead;

WORD_VAL wholeMsgLen;

WORD_VAL snmpMsgLen;

UINT8* msgAuthParamOffsetOutWholeMsg;

UINT8* scopedPduOffset;

WORD scopedPduStructLen;

BYTE scopedPduAuthStructVal;

} SNMPV3_RESPONSE_WHOLEMSG;

Description

This is type SNMPV3_RESPONSE_WHOLEMSG.

10.15.6.12

snmpV3EngnUserDataBase Structure

File

UINT8 userName[SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE];

C typedef struct

{

UINT8 userAuthPswd[SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE];

UINT8 userPrivPswd[SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE];

UINT8 userAuthPswdLoclizdKey[SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE];

UINT8 userPrivPswdLoclizdKey[SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE];

UINT8 userAuthLocalKeyHmacIpad[64];

UINT8 userAuthLocalKeyHmacOpad[64];

UINT8 userDBIndex;

UINT8 userHashType;

UINT8 userNameLength;

UINT8 userAuthPswdLen;

UINT8 userPrivPswdLen;

Types

421

10.15 SNMP Microchip TCP/IP Stack Help Types

UINT8 userPrivType;

} snmpV3EngnUserDataBase;

Members

Members Description

UINT8 userAuthPswd[SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE];

RFC specifies not to save password with the managed nodes instead store pswd ipad and opad values.

UINT8 userAuthLocalKeyHmacIpad[64]; UINT8 userPrivPswdLoclizdKey[20];

Description

This is type snmpV3EngnUserDataBase.

10.15.6.13

SNMPV3MSGDATA Structure

File

C typedef struct

{

UINT8 * head;

WORD length;

WORD maxlength;

WORD msgAuthParamOffset;

} SNMPV3MSGDATA;

Description

SNMPv3

10.15.6.14

snmpV3TrapConfigDataBase Structure

File

UINT8 userSecurityName[USER_SECURITY_NAME_LEN];

C typedef struct

{

STD_BASED_SNMP_MESSAGE_PROCESSING_MODEL messageProcessingModelType;

STD_BASED_SNMP_SECURITY_MODEL securityModelType;

STD_BASED_SNMPV3_SECURITY_LEVEL securityLevelType;

} snmpV3TrapConfigDataBase;

Description

snmpv3 target configuration with respect to trap.

10.15.6.15

statusInformation Structure

File

C typedef struct

registerContextEngineID {

BYTE* contextEngineID;

BYTE pduType;

} statusInformation;

422

10.15 SNMP

Members

BYTE* contextEngineID;

BYTE pduType;

Description

success or errorIndication

Microchip TCP/IP Stack Help

Description

take responsibility for this one the pduType(s) to be registered

Types

10.15.6.16

STD_BASED_SNMP_MESSAGE_PROCESSING_MODEL

Enumeration

File

C typedef enum

{

SNMPV1_MSG_PROCESSING_MODEL = 0X00,

SNMPV2C_MSG_PROCESSING_MODEL = 0X01,

SNMPV2U_V2_MSG_PROCESSING_MODEL = 0X02,

SNMPV3_MSG_PROCESSING_MODEL = 0X03

} STD_BASED_SNMP_MESSAGE_PROCESSING_MODEL;

Description

This is type STD_BASED_SNMP_MESSAGE_PROCESSING_MODEL.

10.15.6.17

STD_BASED_SNMP_SECURITY_MODEL Enumeration

File

C typedef enum

{

ANY_SECUTIRY_MODEL = 0x00,

SNMPV1_SECURITY_MODEL = 0X01,

SNMPV2C_SECURITY_MODEL = 0X02,

SNMPV3_USM_SECURITY_MODEL = 0X03

} STD_BASED_SNMP_SECURITY_MODEL;

Description

Snmp Message Processing Model

10.15.6.18

STD_BASED_SNMPV3_SECURITY_LEVEL Enumeration

File

C typedef enum

{

NO_AUTH_NO_PRIV = 1,

AUTH_NO_PRIV,

AUTH_PRIV

} STD_BASED_SNMPV3_SECURITY_LEVEL;

Description

This is type STD_BASED_SNMPV3_SECURITY_LEVEL.

423

10.15 SNMP Microchip TCP/IP Stack Help

10.15.6.19

USM_SECURITY_LEVEL Enumeration

File

C typedef enum

{

noAuthProtocol = 0x1,

hmacMD5Auth,

hmacSHAAuth,

noPrivProtocol,

desPrivProtocol = 0x5,

aesPrivProtocol = 0x6

} USM_SECURITY_LEVEL;

Description

This is type USM_SECURITY_LEVEL.

Variables

10.15.7

Variables

Module

authKey_iPad ( see page 426)

Variables

Name

Description

This is variable authKey_iPad.

authKey_oPad ( see page 426)

This is variable authKey_oPad.

authoritativeSnmpEngineBoots ( see page 426)

authoritativeSnmpEngineTime ( see page 427) cipher_text ( see page 427) deciphered_text ( see page 427)

The number of times that the authoritative SNMP engine has

(re-)initialized itself since its snmpEngineID ( see page 433) was

last configured.

The number of seconds since the value of the

authoritativeSnmpEngineBoots ( see page 426) object last changed

This is variable cipher_text.

This is variable deciphered_text.

getZeroInstance ( see page 427)

This variable is used for gext next request for zero instance

gSnmpV3InPduWholeMsgBuf ( see page 427)

Dynamic memory stub and PDU details for Incoming stored PDU

gSnmpV3OUTPduWholeMsgBuf ( see page 428)

Dynamic memory stub details and constructed outgoing stored PDU details

Response PDU construction offset details

gSNMPv3PduHeaderBuf ( see page

428) gSNMPv3ScopedPduDataPos ( see page 428) gSNMPv3ScopedPduRequestBuf ( see page 428)

Offset to read scoped PDU data bytes for processing from dynamic memory stub

Stored request scoped pdu details

gSNMPv3ScopedPduResponseBuf ( see page 429) gSnmpv3TrapConfigData ( see page

429)

Processed response scoped pdu details

SNMPv3 global configuration database to be used for trap notification

424

10.15 SNMP Microchip TCP/IP Stack Help Variables

gSNMPv3TrapMsgHeaderBuf ( see page 429)

TRAP message PDU header construction offset details

gSnmpV3TrapOUTPduWholeMsgBuf

gSNMPv3TrapScopedPduResponseBuf

Dynamic memory stub details and constructed trap PDU details

gSNMPV3TrapSecurityLevel ( see page 430)

TRAP scoped PDU construction offset details

This is variable gSNMPV3TrapSecurityLevel.

gSnmpv3UserDBIndex ( see page

430)

Index to the particular reference configured in User security model

data base snmpV3UserDataBase ( see page 437).

gUsmStatsEngineID ( see page 430)

Global variable to find out how many times SNMPv3 engine id has been validated

hmacAuthKeyBuf ( see page 430)

HmacMd5Digest ( see page 431)

HmacSHADigest ( see page 431)

This is variable hmacAuthKeyBuf.

This is variable HmacMd5Digest.

This is variable HmacSHADigest.

incomingPdu ( see page 431) incomingSnmpPDUmsgID ( see page

ivEncrptKeyOut ( see page 431)

Incoming PDU details

Retrived Incoming Msg ID value from PDU

This is variable ivEncrptKeyOut.

md5LocalizedAuthKey ( see page 432) This is variable md5LocalizedAuthKey.

msgSecrtyParamLenOffset ( see page

securityPrimitivesOfIncomingPdu ( see page 432)

This is variable msgSecrtyParamLenOffset.

Incoming PDU Security primitive details.

session_key ( see page 432)

sha1LocalizedAuthKey ( see page

433) snmpEngineBoots ( see page 433)

This is variable session_key.

This is variable sha1LocalizedAuthKey.

snmpEngineID ( see page 433)

The number of times that the SNMP engine has (re-)initialized itself

since snmpEngineID ( see page 433) was last configured.

Reserving 32 bytes for the snmpEngineID as the octet string length can vary form 5 to 32

The maximum message size the SNMP engine can handle.

snmpEngineMaxMessageSize ( see page 433) snmpEngineMsgProcessModel ( see page 433)

Type of Message processing model used. Value Maximum range

(2^31-1), RFC3411

snmpEngineSecurityModel ( see page

snmpEngineTime ( see page 434)

Type of security model used. Value Maximum range (2^31-1),

RFC3411

The number of seconds since the value of the snmpEngineBoots ( see page 433) object last changed

snmpEngineTimeOffset ( see page

snmpEngnIDLength ( see page 434)

Stores the time value in seconds since SNMP Engine reset

Engine ID length of the SNMP Engine

snmpInMsgAuthParamLen ( see page

snmpInMsgAuthParamStrng ( see page 435) snmpInMsgPrivParamLen ( see page

Incoming SNMPv3 msg authentication parameters string is 12 bytes long.

snmpInMsgPrvParamStrng ( see page

Reserving 12 bytes for the incoming SNMPv3 msg authentication parameters.

Incoming SNMPv3 msg privacy parameters string is 8 bytes long.

snmpMsgBufSeekPos ( see page 435) Offset to read PDU data bytes for processing from dynamic memory

Reserving 8 bytes for the incoming SNMPv3 msg privacy parameters.

stub

snmpOutMsgAuthParamLen ( see page 436)

Outgoing SNMPv3 msg authentication parameters string is 12 bytes long.

425

10.15 SNMP Microchip TCP/IP Stack Help Variables

snmpOutMsgAuthParamStrng ( see page 436) snmpOutMsgPrivParamLen ( see page 436) snmpOutMsgPrvParamStrng ( see page 436)

snmpResponseSecurityFlag ( see page 437) snmpSecurityLevel ( see page 437) snmpV3AesDecryptInitVector ( see page 437) snmpV3AesEncryptInitVector ( see page 437) snmpV3UserDataBase ( see page

437)

Reserving 12 bytes for the outgoing SNMPv3 msg authentication parameters.

Outgoing SNMPv3 msg privacy parameters string is 8 bytes long.

Reserving 8 bytes for the outgoing SNMPv3 msg privacy parameters.

Type of Security for outgoing message in response to the incoming message.

Type of security. noAuthNoPriv(0),AuthNoPriv(1),AuthPriv(3)

128 Bit

This is variable snmpV3UserDataBase.

10.15.7.1

authKey_iPad Variable

File

UINT8 authKey_iPad[64];

Description

This is variable authKey_iPad.

10.15.7.2

authKey_oPad Variable

File

UINT8 authKey_oPad[64];

Description

This is variable authKey_oPad.

10.15.7.3

authoritativeSnmpEngineBoots Variable

File

The number of times that the authoritative SNMP engine has (re-)initialized itself since its snmpEngineID ( see page 433)

DWORD_VAL authoritativeSnmpEngineBoots;

Description

was last configured.

426

10.15 SNMP Microchip TCP/IP Stack Help

10.15.7.4

authoritativeSnmpEngineTime Variable

File

The number of seconds since the value of the authoritativeSnmpEngineBoots ( see page 426) object last changed

DWORD_VAL authoritativeSnmpEngineTime;

Description

10.15.7.5

cipher_text Variable

File

UINT8 cipher_text[16];

Description

This is variable cipher_text.

10.15.7.6

deciphered_text Variable

File

UINT8 deciphered_text[16];

Description

This is variable deciphered_text.

10.15.7.7

getZeroInstance Variable

File

BOOL getZeroInstance = FALSE;

Description

This variable is used for gext next request for zero instance

10.15.7.8

gSnmpV3InPduWholeMsgBuf Variable

File

SNMPV3_REQUEST_WHOLEMSG gSnmpV3InPduWholeMsgBuf = {NULL,NULL,{0},{0},0,0,0,0};

Variables

427

10.15 SNMP Microchip TCP/IP Stack Help

Description

Dynamic memory stub and PDU details for Incoming stored PDU

10.15.7.9

gSnmpV3OUTPduWholeMsgBuf Variable

File

SNMPV3_RESPONSE_WHOLEMSG gSnmpV3OUTPduWholeMsgBuf = {NULL,NULL,{0},{0},0,0,0,0};

Description

Dynamic memory stub details and constructed outgoing stored PDU details

10.15.7.10

gSNMPv3PduHeaderBuf Variable

File

SNMPV3MSGDATA gSNMPv3PduHeaderBuf = {NULL,0,0,0};

Description

Response PDU construction offset details

10.15.7.11

gSNMPv3ScopedPduDataPos Variable

File

UINT16 gSNMPv3ScopedPduDataPos = 0;

Description

Offset to read scoped PDU data bytes for processing from dynamic memory stub

10.15.7.12

gSNMPv3ScopedPduRequestBuf Variable

File

SNMPV3MSGDATA gSNMPv3ScopedPduRequestBuf = {NULL,0,0,0};

Description

Stored request scoped pdu details

Variables

428

10.15 SNMP Microchip TCP/IP Stack Help

10.15.7.13

gSNMPv3ScopedPduResponseBuf Variable

File

SNMPV3MSGDATA gSNMPv3ScopedPduResponseBuf = {NULL,0,0,0};

Description

Processed response scoped pdu details

10.15.7.14

gSnmpv3TrapConfigData Variable

File

snmpV3TrapConfigDataBase gSnmpv3TrapConfigData[SNMPV3_USM_MAX_USER] = { \

{"microchip",SNMPV3_MSG_PROCESSING_MODEL,SNMPV3_USM_SECURITY_MODEL,AUTH_PRIV}, \

{"SnmpAdmin",SNMPV3_MSG_PROCESSING_MODEL,SNMPV3_USM_SECURITY_MODEL,AUTH_NO_PRIV}, \

{"root",SNMPV3_MSG_PROCESSING_MODEL,SNMPV3_USM_SECURITY_MODEL,NO_AUTH_NO_PRIV} \ };

Description

SNMPv3 global configuration database to be used for trap notification

10.15.7.15

gSNMPv3TrapMsgHeaderBuf Variable

File

SNMPV3MSGDATA gSNMPv3TrapMsgHeaderBuf;

Description

TRAP message PDU header construction offset details

10.15.7.16

gSnmpV3TrapOUTPduWholeMsgBuf Variable

File

SNMPV3_RESPONSE_WHOLEMSG gSnmpV3TrapOUTPduWholeMsgBuf = {NULL,NULL,{0},{0},0,0,0,0};

Description

Dynamic memory stub details and constructed trap PDU details

10.15.7.17

gSNMPv3TrapScopedPduResponseBuf Variable

File

SNMPV3MSGDATA gSNMPv3TrapScopedPduResponseBuf = {NULL,0,0,0};

Variables

429

10.15 SNMP Microchip TCP/IP Stack Help

Description

TRAP scoped PDU construction offset details

Variables

10.15.7.18

gSNMPV3TrapSecurityLevel Variable

File

UINT8 gSNMPV3TrapSecurityLevel = NO_REPORT_NO_PRIVACY_NO_AUTH;

Description

This is variable gSNMPV3TrapSecurityLevel.

10.15.7.19

gSnmpv3UserDBIndex Variable

File

Index to the particular reference configured in User security model data base snmpV3UserDataBase ( see page 437).

WORD gSnmpv3UserDBIndex;

Description

10.15.7.20

gUsmStatsEngineID Variable

File

WORD_VAL gUsmStatsEngineID = {0};

Description

Global variable to find out how many times SNMPv3 engine id has been validated

10.15.7.21

hmacAuthKeyBuf Variable

File

UINT8 hmacAuthKeyBuf[64];

Description

This is variable hmacAuthKeyBuf.

430

10.15 SNMP Microchip TCP/IP Stack Help

10.15.7.22

HmacMd5Digest Variable

File

UINT8 HmacMd5Digest[16];

Description

This is variable HmacMd5Digest.

10.15.7.23

HmacSHADigest Variable

File

UINT8 HmacSHADigest[20];

Description

This is variable HmacSHADigest.

10.15.7.24

incomingPdu Variable

File

dispatcherProcessPdu incomingPdu;

C struct

Description

Incoming PDU details

10.15.7.25

incomingSnmpPDUmsgID Variable

File

DWORD_VAL incomingSnmpPDUmsgID;

Description

Retrived Incoming Msg ID value from PDU

10.15.7.26

ivEncrptKeyOut Variable

File

Variables

431

10.15 SNMP

UINT8 ivEncrptKeyOut[16];

Description

This is variable ivEncrptKeyOut.

Microchip TCP/IP Stack Help

10.15.7.27

md5LocalizedAuthKey Variable

File

UINT8 md5LocalizedAuthKey[16];

Description

This is variable md5LocalizedAuthKey.

10.15.7.28

msgSecrtyParamLenOffset Variable

File

WORD msgSecrtyParamLenOffset;

Description

This is variable msgSecrtyParamLenOffset.

10.15.7.29

securityPrimitivesOfIncomingPdu Variable

File

SecuritySysProcessIncomingMsg securityPrimitivesOfIncomingPdu;

Description

Incoming PDU Security primitive details.

10.15.7.30

session_key Variable

File

AES_SESSION_KEY_128_BIT session_key;

Description

This is variable session_key.

Variables

432

10.15 SNMP Microchip TCP/IP Stack Help Variables

10.15.7.31

sha1LocalizedAuthKey Variable

File

UINT8 sha1LocalizedAuthKey[20];

Description

This is variable sha1LocalizedAuthKey.

10.15.7.32

snmpEngineBoots Variable

File

The number of times that the SNMP engine has (re-)initialized itself since snmpEngineID ( see page 433) was last

UINT32 snmpEngineBoots = 0;

Description

configured.

10.15.7.33

snmpEngineID Variable

File

UINT8 snmpEngineID[32+1];

Description

Reserving 32 bytes for the snmpEngineID as the octet string length can vary form 5 to 32

10.15.7.34

snmpEngineMaxMessageSize Variable

File

DWORD_VAL snmpEngineMaxMessageSize;

Description

The maximum message size the SNMP engine can handle.

10.15.7.35

snmpEngineMsgProcessModel Variable

File

433

10.15 SNMP Microchip TCP/IP Stack Help

UINT32 snmpEngineMsgProcessModel = 0;

Description

Type of Message processing model used. Value Maximum range (2^31-1), RFC3411

10.15.7.36

snmpEngineSecurityModel Variable

File

UINT32 snmpEngineSecurityModel = 0;

Description

Type of security model used. Value Maximum range (2^31-1), RFC3411

10.15.7.37

snmpEngineTime Variable

File

The number of seconds since the value of the snmpEngineBoots ( see page 433) object last changed

DWORD_VAL snmpEngineTime;

Description

10.15.7.38

snmpEngineTimeOffset Variable

File

DWORD snmpEngineTimeOffset = 0;

Description

Stores the time value in seconds since SNMP Engine reset

10.15.7.39

snmpEngnIDLength Variable

File

UINT8 snmpEngnIDLength = 0;

Description

Engine ID length of the SNMP Engine

Variables

434

10.15 SNMP Microchip TCP/IP Stack Help

10.15.7.40

snmpInMsgAuthParamLen Variable

File

UINT8 snmpInMsgAuthParamLen;

Description

Incoming SNMPv3 msg authentication parameters string is 12 bytes long.

10.15.7.41

snmpInMsgAuthParamStrng Variable

File

UINT8 snmpInMsgAuthParamStrng[];

Description

Reserving 12 bytes for the incoming SNMPv3 msg authentication parameters.

10.15.7.42

snmpInMsgPrivParamLen Variable

File

UINT8 snmpInMsgPrivParamLen = 8;

Description

Incoming SNMPv3 msg privacy parameters string is 8 bytes long.

10.15.7.43

snmpInMsgPrvParamStrng Variable

File

UINT8 snmpInMsgPrvParamStrng[];

Description

Reserving 8 bytes for the incoming SNMPv3 msg privacy parameters.

10.15.7.44

snmpMsgBufSeekPos Variable

File

Variables

435

10.15 SNMP Microchip TCP/IP Stack Help

UINT16 snmpMsgBufSeekPos = 0;

Description

Offset to read PDU data bytes for processing from dynamic memory stub

10.15.7.45

snmpOutMsgAuthParamLen Variable

File

UINT8 snmpOutMsgAuthParamLen;

Description

Outgoing SNMPv3 msg authentication parameters string is 12 bytes long.

10.15.7.46

snmpOutMsgAuthParamStrng Variable

File

UINT8 snmpOutMsgAuthParamStrng[];

Description

Reserving 12 bytes for the outgoing SNMPv3 msg authentication parameters.

10.15.7.47

snmpOutMsgPrivParamLen Variable

File

UINT8 snmpOutMsgPrivParamLen = 8;

Description

Outgoing SNMPv3 msg privacy parameters string is 8 bytes long.

10.15.7.48

snmpOutMsgPrvParamStrng Variable

File

UINT8 snmpOutMsgPrvParamStrng[];

Description

Reserving 8 bytes for the outgoing SNMPv3 msg privacy parameters.

Variables

436

10.15 SNMP Microchip TCP/IP Stack Help

10.15.7.49

snmpResponseSecurityFlag Variable

File

UINT8 snmpResponseSecurityFlag = 0;

Description

Type of Security for outgoing message in response to the incoming message.

10.15.7.50

snmpSecurityLevel Variable

File

UINT8 snmpSecurityLevel = 0;

Description

Type of security. noAuthNoPriv(0),AuthNoPriv(1),AuthPriv(3)

10.15.7.51

snmpV3AesDecryptInitVector Variable

File

UINT8 snmpV3AesDecryptInitVector[16+1];

Description

128 Bit

10.15.7.52

snmpV3AesEncryptInitVector Variable

File

UINT8 snmpV3AesEncryptInitVector[16+1];

Description

128 Bit

10.15.7.53

snmpV3UserDataBase Variable

File

snmpV3EngnUserDataBase snmpV3UserDataBase[SNMPV3_USM_MAX_USER];

Variables

437

10.15 SNMP Microchip TCP/IP Stack Help

Description

This is variable snmpV3UserDataBase.

Macros

10.15.8

Macros

Macros

Name

AUTH_LOCALIZED_PASSWORD_KEY_LEN ( see page 439)

INVALID_INDEX ( see page 439)

IS_SNMPV3_AUTH_STRUCTURE ( see page 440)

MSG_AUTHORITATIVE_HEADER_LEN ( see page 440)

MSGGLOBAL_HEADER_LEN ( see page 440)

PRIV_LOCALIZED_PASSWORD_KEY_LEN ( see page 441)

REPORT_RESPONSE ( see page 441)

SNMP_ENGINE_MAX_MSG_SIZE ( see page 441)

Description

SNMPv3 Authentication ( see page 91)

Localized passwed key lenegth size

This is macro INVALID_INDEX.

This is macro

IS_SNMPV3_AUTH_STRUCTURE.

Length of SNMPv3 authoratative msg header length = Header length ( 2 + 2

bytes) + engineID ( snmpEngnIDLength

( see page 434) bytes)

• engine boot( 4 bytes)+ engine time(4 bytes)

+security name

(securityPrimitivesOfIncomingPdu ( see page 432) value) +authentication

parameters

(snmpOutMsgAuthParamLen ( see page 436) value) +privacy parameters

(snmpOutMsgAuthParamLen ( see page 436) value)

Length of the SNMPv3 msg header(x) =

Header length (2 bytes)

• MSGID size (type(1 byte) + length of value(1 byte)+4 bytes value)

• msgMAXSIZE(type + length of value +4 bytes value)

• msg flag(type + length of value +1 byte value)

• security model type(type + length of value +1 byte value)

#define

PRIV_LOCALIZED_PASSWORD_KEY_

LEN

16 SNMPv3 Privacy Pasword key length size

This is macro REPORT_RESPONSE.

SNMP_ENGINE_MAX_MSG_SIZE is determined as the minimum of the max msg size values supported among all of the transports available to and supported by the engine.

438

10.15 SNMP Microchip TCP/IP Stack Help Macros

SNMP_MAX_MSG_SIZE ( see page 441)

SNMP_MAX_OID_LEN_MEM_USE ( see page 442)

SNMP MIN and MAX message 484 bytes in size As per RFC 3411

snmpEngineMaxMessageSize ( see page 433) and RFC 1157 ( section 4-

protocol specification ) and implementation supports more than 484 whenever feasible.

This macro will be used to avoid SNMP

OID memory buffer corruption

This macro will be used to avoid SNMP

OID memory buffer corruption

SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE ( see page

442)

SNMP_V3 ( see page 442)

This is macro SNMP_V3.

SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE

SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE

SNMPv3 authentication localized Key length for memory validation

SNMPV3_H ( see page 443)

( see page 443)

This is macro SNMPV3_H.

SNMPv3 privacy key length size for memory validation

SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE ( see page

443)

SNMPV3_USM_MAX_USER ( see page 443)

User security name length for memory validation

User Security Model should have atleast

1 user. Default is 3. User should change as per the requirement.

SNMPV3MSG_AUTHENTICATION_FAIL ( see page 444)

SNMPV3MSG_AUTHENTICATION_SUCCESS ( see page 444)

USER_SECURITY_NAME_LEN ( see page 444)

This is macro

SNMPV3MSG_AUTHENTICATION_FAI

This is macro

SNMPV3MSG_AUTHENTICATION_SU

CCESS.

SNMPv3 User Security Name length

Module

10.15.8.1

AUTH_LOCALIZED_PASSWORD_KEY_LEN Macro

File

SNMPv3 Authentication ( see page 91) Localized passwed key lenegth size

#define

AUTH_LOCALIZED_PASSWORD_KEY_LEN (20)

Description

10.15.8.2

INVALID_INDEX Macro

File

#define

INVALID_INDEX 0xFF

Description

This is macro INVALID_INDEX.

439

10.15 SNMP Microchip TCP/IP Stack Help Macros

10.15.8.3

IS_SNMPV3_AUTH_STRUCTURE Macro

File

#define

IS_SNMPV3_AUTH_STRUCTURE(a) (a==SNMPV3_ENCRYPTION)

Description

This is macro IS_SNMPV3_AUTH_STRUCTURE.

10.15.8.4

MSG_AUTHORITATIVE_HEADER_LEN Macro

File

+1+1+securityPrimitivesOfIncomingPdu.securityNameLength

#define

MSG_AUTHORITATIVE_HEADER_LEN(x) ( x=(2+2 \

+1+1+snmpEngnIDLength \

+1+1+4 \

+1+1+snmpOutMsgAuthParamLen \

+1+1+snmpOutMsgPrivParamLen) \

)

Description

Length of SNMPv3 authoratative msg header length = Header length ( 2 + 2 bytes) + engineID ( snmpEngnIDLength ( see page 434) bytes)

• engine boot( 4 bytes)+ engine time(4 bytes)

+security name

(securityPrimitivesOfIncomingPdu ( see page 432)

value) +authentication parameters

(snmpOutMsgAuthParamLen ( see page 436) value) +privacy parameters (snmpOutMsgAuthParamLen ( see page 436)

value)

10.15.8.5

MSGGLOBAL_HEADER_LEN Macro

File

#define

MSGGLOBAL_HEADER_LEN(x) ( x= (2 \

+1+1+4 \

+1+1+1 \

+1+1+1)\

)

Description

Length of the SNMPv3 msg header(x) = Header length (2 bytes)

• MSGID size (type(1 byte) + length of value(1 byte)+4 bytes value)

• msgMAXSIZE(type + length of value +4 bytes value)

• msg flag(type + length of value +1 byte value)

440

10.15 SNMP Microchip TCP/IP Stack Help

• security model type(type + length of value +1 byte value)

10.15.8.6

PRIV_LOCALIZED_PASSWORD_KEY_LEN Macro

File

#define

PRIV_LOCALIZED_PASSWORD_KEY_LEN (20)

Description

#define PRIV_LOCALIZED_PASSWORD_KEY_LEN 16 SNMPv3 Privacy Pasword key length size

10.15.8.7

REPORT_RESPONSE Macro

File

#define

REPORT_RESPONSE (0xa8)

Description

This is macro REPORT_RESPONSE.

Macros

10.15.8.8

SNMP_ENGINE_MAX_MSG_SIZE Macro

File

#define

SNMP_ENGINE_MAX_MSG_SIZE 1024

Description

SNMP_ENGINE_MAX_MSG_SIZE is determined as the minimum of the max msg size values supported among all of the transports available to and supported by the engine.

10.15.8.9

SNMP_MAX_MSG_SIZE Macro

File

SNMP MIN and MAX message 484 bytes in size As per RFC 3411 snmpEngineMaxMessageSize ( see page 433) and

#define

SNMP_MAX_MSG_SIZE 484

Description

RFC 1157 ( section 4- protocol specification ) and implementation supports more than 484 whenever feasible.

441

10.15 SNMP Microchip TCP/IP Stack Help Macros

10.15.8.10

SNMP_MAX_OID_LEN_MEM_USE Macro

File

#define

SNMP_MAX_OID_LEN_MEM_USE (18)

Description

This macro will be used to avoid SNMP OID memory buffer corruption

10.15.8.11

SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE

Macro

File

#define

SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE (8)

Description

This macro will be used to avoid SNMP OID memory buffer corruption

10.15.8.12

SNMP_V3 Macro

File

#define

SNMP_V3 (3)

Description

This is macro SNMP_V3.

10.15.8.13

SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE

Macro

File

SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE (AUTH_LOCALIZED_PASSWORD_KEY_LEN+1)

#define

Description

SNMPv3 authentication localized Key length for memory validation

442

10.15 SNMP Microchip TCP/IP Stack Help Macros

10.15.8.14

SNMPV3_H Macro

File

#define

SNMPV3_H

Description

This is macro SNMPV3_H.

10.15.8.15

SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE

Macro

File

SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE (PRIV_LOCALIZED_PASSWORD_KEY_LEN+1)

#define

Description

SNMPv3 privacy key length size for memory validation

10.15.8.16

SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE

Macro

File

SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE (USER_SECURITY_NAME_LEN+1)

#define

Description

User security name length for memory validation

10.15.8.17

SNMPV3_USM_MAX_USER Macro

File

#define

SNMPV3_USM_MAX_USER 3

//User Security Model should have atleast 1 user. Default is

3. User should change as per the requirement.

Description

User Security Model should have atleast 1 user. Default is 3. User should change as per the requirement.

443

10.15 SNMP Microchip TCP/IP Stack Help

10.15.8.18

SNMPV3MSG_AUTHENTICATION_FAIL Macro

File

#define

SNMPV3MSG_AUTHENTICATION_FAIL 0

Description

This is macro SNMPV3MSG_AUTHENTICATION_FAIL.

10.15.8.19

SNMPV3MSG_AUTHENTICATION_SUCCESS Macro

File

#define

SNMPV3MSG_AUTHENTICATION_SUCCESS 1

Description

This is macro SNMPV3MSG_AUTHENTICATION_SUCCESS.

10.15.8.20

USER_SECURITY_NAME_LEN Macro

File

#define

USER_SECURITY_NAME_LEN (16)

Description

SNMPv3 User Security Name length

Files

10.15.9

Files

Files

Name

Description

• Simple Network Management Protocol (SNMP) Version 3 Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMPv3 API for doing stuff

• -Reference: RFCs 3410, 3411, 3412, 3413, 3414

444

10.15 SNMP

Microchip TCP/IP Stack Help

• Simple Network Management Protocol (SNMP) Version 3 Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMPv3 API for doing stuff

• -Reference: RFCs 3410, 3411, 3412, 3413, 3414

• Simple Network Management Protocol (SNMP) Version 3 Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMPv3 API for doing stuff

• -Reference: RFCs 3410, 3411, 3412, 3413, 3414

• Simple Network Management Protocol (SNMP) Version 1 Agent

• Simple Network Management Protocol (SNMP) Version 2 community based Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMP API for doing stuff

• -Reference: RFC 1157 (for SNMP V1)

• RFC 3416 (for SNMPv2C)

• SNMP Defs for Microchip TCP/IP Stack

Files

Module

_Snmpv3IsValidAuthStructure

10.15.9.1

SNMPv3.c

Functions

Name

( see page 379)

Description

Decode variable length structure.

FindOIDsFromSnmpV3Request

( see page 381)

Finds number of varbinds in the varbind list received in a SNMPv3 pdu.

IsSnmpV3ASNNull ( see page 382)

Verifies the value type as ASN_NULL ( see page 349).

Populates OID type, length and oid string from the received pdu.

IsSnmpv3ValidOID ( see page 382)

IsSNMPv3ValidStructure ( see page 383)

Snmpv3FreeDynAllocMem ( see page 395)

Snmpv3IsValidAuthStructure

( see page 398)

Decode variable length structure.

Allocated dynamic memory freeing is done by this routine.

Decode variable length structure.

445

10.15 SNMP Microchip TCP/IP Stack Help

Snmpv3IsValidInt ( see page

399)

Snmpv3ReportPdu ( see page 401)

Snmpv3SetErrorStatus ( see page 402)

Verifies variable datatype as INT and retrieves its value.

Constructs the report pdu infomration for the Report Pdu.

Set snmpv3 error status in the response pdu.

Macros

Files

Name

INVALID_INDEX ( see page 439)

Description

This is macro INVALID_INDEX.

MSG_AUTHORITATIVE_HEADER_LEN

( see page 440)

Length of SNMPv3 authoratative msg header length = Header length

( 2 + 2 bytes) + engineID ( snmpEngnIDLength ( see page 434)

bytes)

• engine boot( 4 bytes)+ engine time(4 bytes)

+security name (securityPrimitivesOfIncomingPdu ( see page

(snmpOutMsgAuthParamLen ( see page 436) value) +privacy parameters (snmpOutMsgAuthParamLen ( see page 436) value)

value) +authentication parameters

MSGGLOBAL_HEADER_LEN ( see page 440)

Length of the SNMPv3 msg header(x) = Header length (2 bytes)

• MSGID size (type(1 byte) + length of value(1 byte)+4 bytes value)

• msgMAXSIZE(type + length of value +4 bytes value)

• msg flag(type + length of value +1 byte value)

• security model type(type + length of value +1 byte value)

SNMP_ENGINE_MAX_MSG_SIZE ( see page 441)

SNMP_ENGINE_MAX_MSG_SIZE is determined as the minimum of the max msg size values supported among all of the transports available to and supported by the engine.

Variables

Name

gSnmpV3InPduWholeMsgBuf ( see page 427)

Description

Dynamic memory stub and PDU details for Incoming stored PDU

gSnmpV3OUTPduWholeMsgBuf ( see page 428)

Dynamic memory stub details and constructed outgoing stored PDU details

Response PDU construction offset details

gSNMPv3PduHeaderBuf ( see page

428) gSNMPv3ScopedPduDataPos ( see page 428) gSNMPv3ScopedPduRequestBuf ( see page 428)

Offset to read scoped PDU data bytes for processing from dynamic memory stub

Stored request scoped pdu details

gSNMPv3ScopedPduResponseBuf ( see page 429) gSnmpv3TrapConfigData ( see page

429)

Processed response scoped pdu details

SNMPv3 global configuration database to be used for trap notification

gSnmpV3TrapOUTPduWholeMsgBuf

gSNMPv3TrapScopedPduResponseBuf

Dynamic memory stub details and constructed trap PDU details

gSNMPV3TrapSecurityLevel ( see page 430)

TRAP scoped PDU construction offset details

This is variable gSNMPV3TrapSecurityLevel.

gUsmStatsEngineID ( see page 430)

Global variable to find out how many times SNMPv3 engine id has been validated

446

10.15 SNMP Microchip TCP/IP Stack Help Files

incomingPdu ( see page 431) incomingSnmpPDUmsgID ( see page

msgSecrtyParamLenOffset ( see page

Incoming PDU details

Retrived Incoming Msg ID value from PDU

securityPrimitivesOfIncomingPdu ( see page 432)

This is variable msgSecrtyParamLenOffset.

Incoming PDU Security primitive details.

snmpEngineBoots ( see page 433)

The number of times that the SNMP engine has (re-)initialized itself

since snmpEngineID ( see page 433) was last configured.

snmpEngineID ( see page 433)

snmpEngineTimeOffset ( see page

snmpEngineMaxMessageSize ( see page 433) snmpEngineMsgProcessModel ( see page 433)

Reserving 32 bytes for the snmpEngineID as the octet string length can vary form 5 to 32

The maximum message size the SNMP engine can handle.

snmpEngineSecurityModel ( see page

snmpEngineTime ( see page 434)

Type of security model used. Value Maximum range (2^31-1),

RFC3411

Type of Message processing model used. Value Maximum range

(2^31-1), RFC3411

The number of seconds since the value of the snmpEngineBoots ( see page 433) object last changed

Stores the time value in seconds since SNMP Engine reset

snmpEngnIDLength ( see page 434)

Engine ID length of the SNMP Engine

snmpInMsgPrivParamLen ( see page

snmpMsgBufSeekPos ( see page 435) Offset to read PDU data bytes for processing from dynamic memory

Incoming SNMPv3 msg privacy parameters string is 8 bytes long.

stub

Outgoing SNMPv3 msg privacy parameters string is 8 bytes long.

snmpOutMsgPrivParamLen ( see page 436)

snmpResponseSecurityFlag ( see page 437)

Type of Security for outgoing message in response to the incoming message.

snmpSecurityLevel ( see page 437)

SNMPTxOffset ( see page 366)

Type of security. noAuthNoPriv(0),AuthNoPriv(1),AuthPriv(3)

Snmp udp buffer tx offset

Description

• Simple Network Management Protocol (SNMP) Version 3 Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMPv3 API for doing stuff

• -Reference: RFCs 3410, 3411, 3412, 3413, 3414

*******************************************************************

• FileName: SNMPv3.c

• Dependencies: TCP/IP stack

• Processor: PIC32

• Compiler: Microchip C32

• Software License Agreement

447

10.15 SNMP Microchip TCP/IP Stack Help

• reserved.

• Microchip licenses to you the right to use, modify, copy, and

• distribute:

• (i) the Software when embedded on a Microchip microcontroller or

• digital signal controller product ("Device") which is

• integrated into Licensee's product; or

• (ii) ONLY the Software driver source files ENC28J60.c, ENC28J60.h,

• ENCX24J600.c and ENCX24J600.h ported to a non-Microchip device

• used in conjunction with a Microchip ethernet controller for

• the sole purpose of interfacing with the ethernet controller.

• You should refer to the license agreement accompanying this

• Software for additional information regarding your rights and

• obligations.

• THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT

• WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT

• LIMITATION, ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A

• PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL

• MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR

• CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF

• PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS

• BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE

• THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER

• SIMILAR COSTS, WHETHER ASSERTED ON THE BASIS OF CONTRACT, TORT

• (INCLUDING NEGLIGENCE), BREACH OF WARRANTY, OR OTHERWISE.

Files

10.15.9.2

SNMPv3.h

Enumerations

Name

REPORT_FLAG_AND_SECURITY_LEVEL_FLAGS ( see page 417)

SNMP_ENGNID_OCTET_IDENTIFIER_VAL ( see page

419)

SNMPV3_HMAC_HASH_TYPE ( see page 419)

SNMPV3_MSG_AUTH_SEC_PARAM_RESULT ( see page 420)

SNMPV3_MSG_PRIV_SEC_PARAM_RESULT ( see page 420)

SNMPV3_PRIV_PROT_TYPE ( see page 420)

Description

This is type

REPORT_FLAG_AND_SECURITY_LEVEL_FLAG

The fifth octet indicates how the rest (6th and following octets) are formatted. Refer to RFC3411 section5 Page# 41

Type of hash being calculated

This is type

SNMPV3_MSG_AUTH_SEC_PARAM_RESULT.

This is type

SNMPV3_MSG_PRIV_SEC_PARAM_RESULT.

This is type SNMPV3_PRIV_PROT_TYPE.

448

10.15 SNMP Microchip TCP/IP Stack Help Files

STD_BASED_SNMP_MESSAGE_PROCESSING_MODEL

( see page 423)

This is type

STD_BASED_SNMP_MESSAGE_PROCESSING

_MODEL.

STD_BASED_SNMP_SECURITY_MODEL ( see page

STD_BASED_SNMPV3_SECURITY_LEVEL ( see page

Snmp Message Processing Model

USM_SECURITY_LEVEL ( see page 424)

This is type

STD_BASED_SNMPV3_SECURITY_LEVEL.

This is type USM_SECURITY_LEVEL.

Functions

Name

_IsSNMPv3ValidStructure ( see page 379)

Description

Decode variable length structure.

_Snmpv3IsValidInt ( see page 380)

Verifies variable datatype as INT and retrieves its value.

Snmpv3AESEncryptResponseScopedPdu ( see page 388)

outGoing SNMPv3 scoped PDU Encryption using AES encryption protocol.

Snmpv3AuthenticateRxedPduForDataIntegrity ( see page 389)

Authenticate an incoming SNMPV3 USM PDU using

MD5 or SHA

Snmpv3AuthenticateTxPduForDataIntegrity ( see page 389)

Authenticate to an outgoing SNMPV3 USM PDU using

MD5 or SHA

Snmpv3AuthKeyZeroing2HmacBufLen64 ( see page 390)

Pad zero to the authentication key localized buffer.

Snmpv3CmprTrapSecNameAndSecLvlWithUSMDb

Snmpv3ComputeHMACIpadOpadForAuthLoclzedKey

Routine to find the index of the user name in the user data base table.

Snmpv3ComputeHmacMD5Digest ( see page 392)

Compute HMAC inner and outer pad for authorization localized key.

Compute HMAC - MD5 authentication code

Snmpv3ComputeHmacShaDigest ( see page 393)

Compute HMAC - SHA authentication code

Snmpv3ComputeMd5HmacCode ( see page 393)

Snmpv3ComputeShaHmacCode ( see page 394)

Compute HMAC - MD5 authentication code

Compute HMAC - SHA authentication code

Snmpv3GetSecurityLevel ( see page 396)

Snmpv3GetTrapSecurityLevel ( see page 397)

Snmpv3Init ( see page 397)

Snmpv3InitializeUserDataBase ( see page 398)

Snmpv3USMOutMsgPrivParam ( see page 405)

Snmpv3UsmSnmpEngnAuthPrivPswdLocalization ( see page 405)

Get Security level from authentication and Privacy type.

Routine to find the report, auth and privacy flags settings in the TRAP.

SNMPv3 initialization.

Intialize default SNMPv3 global user database.

Snmpv3Pswd2LocalizedAuthKeyMD5Hashing ( see page 400)

Convert MD5 Auth password to the localized Key using

SNMPEngineID.

Snmpv3Pswd2LocalizedAuthKeySHAHashing ( see page 401)

Convert SHA Auth password to the localized Key using

SNMPEngineID.

SNMP USM out message uses Privacy protocol (RFC

3826 )

Convert Auth and Priv password to the localized Key using SNMPEngineID.

Macros

Name

AUTH_LOCALIZED_PASSWORD_KEY_LEN ( see page 439)

PRIV_LOCALIZED_PASSWORD_KEY_LEN ( see page 441)

Description

SNMPv3 Authentication ( see page 91)

Localized passwed key lenegth size

#define

PRIV_LOCALIZED_PASSWORD_KEY_

LEN

16 SNMPv3 Privacy Pasword key length size

449

10.15 SNMP Microchip TCP/IP Stack Help Files

SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE

SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE

SNMPv3 authentication localized Key length for memory validation

SNMPV3_H ( see page 443)

( see page 443)

This is macro SNMPV3_H.

SNMPv3 privacy key length size for memory validation

SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE ( see page

443)

SNMPV3_USM_MAX_USER ( see page 443)

SNMPV3MSG_AUTHENTICATION_FAIL ( see page 444)

User security name length for memory validation

User Security Model should have atleast

1 user. Default is 3. User should change as per the requirement.

This is macro

SNMPV3MSG_AUTHENTICATION_FAI

SNMPV3MSG_AUTHENTICATION_SUCCESS ( see page 444)

USER_SECURITY_NAME_LEN ( see page 444)

This is macro

SNMPV3MSG_AUTHENTICATION_SU

CCESS.

SNMPv3 User Security Name length

Structures

Name

AccessCtrlSubSysIsAccessAllowed ( see page 408)

Description

Applications are the typical clients of the service(s) of the Access

Control Subsystem. The following primitive is provided by the

Access Control Subsystem to check if access is allowed:

statusInformation ( see page 422) = -- success or errorIndication

dispatcherProcessPdu ( see page 409) Process Incoming Request or Notification PDU

Dispatcher provides the following primitive to pass an incoming snmp pdu to an application.

dispatcherStatusInfo ( see page 409)

Generate Outgoing Request or Notification

statusInformation ( see page 422) = -- sendPduHandle if success --

errorIndication if failure

dispathcerReturnResponsePdu ( see page 410)

MsgProcModPrepareDataElements ( see page 411)

MsgProcModPrepareOutgoingMessage

MsgProcModPrepareResponseMessage

Generate Outgoing Response

The PDU Dispatcher provides the following primitive for an application to return an SNMP Response PDU to the PDU

Dispatcher: result = SUCCESS or FAILURE

Prepare Data Elements from an Incoming SNMP Message

The Message Processing Subsystem provides this service primitive for preparing the abstract data elements from an incoming SNMP message: result = -- SUCCESS or errorIndication

Prepare Outgoing SNMP Request or Notification Message

The Message Processing Subsystem provides this service primitive for preparing an outgoing SNMP Request or Notification Message

processResponsePdu ( see page 413) Process Incoming Response PDU

Prepare an Outgoing SNMP Response Message

The Message Processing Subsystem provides this service primitive for preparing an outgoing SNMP Response Message: result = --

SUCCESS or FAILURE

The PDU Dispatcher provides the following primitive to pass an incoming SNMP Response PDU to an application:

registerContextEngineID ( see page

SecuritySysGenerateRequestMsg ( see page 414)

success or errorIndication

This is record SecuritySysGenerateRequestMsg.

SecuritySysGenerateResponseMsg ( see page 415)

Generate a Response Message

The Security Subsystem provides the following primitive to generate a Response message:

450

10.15 SNMP Microchip TCP/IP Stack Help Files

StateRelease ( see page 415)

unregisterContextEngineID ( see page

416)

SecuritySysProcessIncomingMsg ( see page 418)

SNMPV3_REQUEST_WHOLEMSG ( see page 421)

SNMPV3_RESPONSE_WHOLEMSG

( see page 421) snmpV3EngnUserDataBase ( see page 421)

snmpV3TrapConfigDataBase ( see page 422) statusInformation ( see page 422)

Release State Reference Information

All Subsystems which pass stateReference information also provide a primitive to release the memory that holds the referenced state information

This is record unregisterContextEngineID.

This is type SecuritySysProcessIncomingMsg.

This is type SNMPV3_REQUEST_WHOLEMSG.

This is type SNMPV3_RESPONSE_WHOLEMSG.

This is type snmpV3EngnUserDataBase.

snmpv3 target configuration with respect to trap.

success or errorIndication

Description

• Simple Network Management Protocol (SNMP) Version 3 Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMPv3 API for doing stuff

• -Reference: RFCs 3410, 3411, 3412, 3413, 3414

*******************************************************************

• FileName: SNMPv3.h

• Dependencies: TCP/IP stack

• Processor: PIC32

• Compiler: Microchip C32

• Software License Agreement

• reserved.

• Microchip licenses to you the right to use, modify, copy, and

• distribute:

• (i) the Software when embedded on a Microchip microcontroller or

• digital signal controller product ("Device") which is

• integrated into Licensee's product; or

• (ii) ONLY the Software driver source files ENC28J60.c, ENC28J60.h,

• ENCX24J600.c and ENCX24J600.h ported to a non-Microchip device

• used in conjunction with a Microchip ethernet controller for

• the sole purpose of interfacing with the ethernet controller.

451

10.15 SNMP Microchip TCP/IP Stack Help

• You should refer to the license agreement accompanying this

• Software for additional information regarding your rights and

• obligations.

• THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT

• WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT

• LIMITATION, ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A

• PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL

• MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR

• CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF

• PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS

• BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE

• THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER

• SIMILAR COSTS, WHETHER ASSERTED ON THE BASIS OF CONTRACT, TORT

• (INCLUDING NEGLIGENCE), BREACH OF WARRANTY, OR OTHERWISE.

Files

10.15.9.3

SNMPv3USM.c

Variables

Name

authKey_iPad ( see page

426)

Description

This is variable authKey_iPad.

authKey_oPad ( see page

426)

This is variable authKey_oPad.

authoritativeSnmpEngineBoots

( see page 426)

The number of times that the authoritative SNMP engine has (re-)initialized

itself since its snmpEngineID ( see page 433) was last configured.

authoritativeSnmpEngineTime

( see page 427)

The number of seconds since the value of the authoritativeSnmpEngineBoots

( see page 426) object last changed

cipher_text ( see page 427)

This is variable cipher_text.

deciphered_text ( see page

427)

This is variable deciphered_text.

TRAP message PDU header construction offset details

gSNMPv3TrapMsgHeaderBuf

gSnmpv3UserDBIndex ( see page 430) hmacAuthKeyBuf ( see page

430)

Index to the particular reference configured in User security model data base

snmpV3UserDataBase ( see page 437).

This is variable hmacAuthKeyBuf.

HmacMd5Digest ( see page

431) ivEncrptKeyOut ( see page

HmacSHADigest ( see page

md5LocalizedAuthKey ( see page 432)

This is variable HmacMd5Digest.

This is variable HmacSHADigest.

This is variable ivEncrptKeyOut.

This is variable md5LocalizedAuthKey.

session_key ( see page 432) This is variable session_key.

sha1LocalizedAuthKey ( see page 433)

This is variable sha1LocalizedAuthKey.

452

10.15 SNMP Microchip TCP/IP Stack Help Files

snmpInMsgAuthParamLen ( see page 435) snmpInMsgAuthParamStrng

( see page 435) snmpInMsgPrvParamStrng ( see page 435)

snmpOutMsgAuthParamLen

( see page 436) snmpOutMsgAuthParamStrng

( see page 436) snmpOutMsgPrvParamStrng

( see page 436)

snmpV3AesDecryptInitVector

( see page 437) snmpV3AesEncryptInitVector

( see page 437) snmpV3UserDataBase ( see page 437)

Incoming SNMPv3 msg authentication parameters string is 12 bytes long.

Reserving 12 bytes for the incoming SNMPv3 msg authentication parameters.

Reserving 8 bytes for the incoming SNMPv3 msg privacy parameters.

Outgoing SNMPv3 msg authentication parameters string is 12 bytes long.

Reserving 12 bytes for the outgoing SNMPv3 msg authentication parameters.

Reserving 8 bytes for the outgoing SNMPv3 msg privacy parameters.

128 Bit

This is variable snmpV3UserDataBase.

Description

• Simple Network Management Protocol (SNMP) Version 3 Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMPv3 API for doing stuff

• -Reference: RFCs 3410, 3411, 3412, 3413, 3414

*******************************************************************

• FileName: SNMPv3USM.c

• Dependencies: TCP/IP stack

• Processor: PIC32

• Compiler: Microchip C32

• Software License Agreement

• reserved.

• Microchip licenses to you the right to use, modify, copy, and

• distribute:

• (i) the Software when embedded on a Microchip microcontroller or

• digital signal controller product ("Device") which is

• integrated into Licensee's product; or

• (ii) ONLY the Software driver source files ENC28J60.c, ENC28J60.h,

• ENCX24J600.c and ENCX24J600.h ported to a non-Microchip device

• used in conjunction with a Microchip ethernet controller for

• the sole purpose of interfacing with the ethernet controller.

453

10.15 SNMP Microchip TCP/IP Stack Help

• You should refer to the license agreement accompanying this

• Software for additional information regarding your rights and

• obligations.

• THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT

• WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT

• LIMITATION, ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A

• PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL

• MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR

• CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF

• PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS

• BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE

• THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER

• SIMILAR COSTS, WHETHER ASSERTED ON THE BASIS OF CONTRACT, TORT

• (INCLUDING NEGLIGENCE), BREACH OF WARRANTY, OR OTHERWISE.

Files

10.15.9.4

SNMP.c

Functions

Name

FindOIDsInRequest ( see page

IsASNNull ( see page 356)

Description

Finds number of varbinds in the varbind list received in a pdu.

IsValidCommunity ( see page

369)

IsValidOID ( see page 370)

Verifies the value type as ASN_NULL ( see page 349).

Verifies for the community string datatype and the max community name and length, this agent can process.

Populates OID type, length and oid string from the received pdu.

IsValidPDU ( see page 370)

ProcessGetSetHeader ( see page 372)

Verifies for the snmp request type.

Validates the received udp packet Get/Set request header.

ProcessHeader ( see page 373)

Validates the received udp packet Snmp header.

ProcessVariables ( see page 374) This routine processes the snmp request and parallely creates the

response pdu.

ReadMIBRecord ( see page 375)

Get OID string from MPFS using the node address.

SNMPCheckIfPvtMibObjRequested

( see page 375)

To find whether requested OID is only for private access.

Variables

Name

appendZeroToOID ( see page 349)

Description

global flag to modify OID by appending zero

dataTypeTable ( see page

getZeroInstance ( see page

427)

SNMPAgentSocket ( see page 365)

ASN format datatype for snmp v1 and v2c

This variable is used for gext next request for zero instance

MPFS file handler

454

10.15 SNMP Microchip TCP/IP Stack Help

SNMPNotifyInfo ( see page

365)

snmpReqVarErrStatus ( see page 366)

SNMPRxOffset ( see page

SNMPStatus ( see page

COMMUNITY_TYPE ( see page 334)

Snmp udp socket notify info for trap vars from req list processing err status

Snmp udp buffer rx offset

MIB file access status

Description

• Simple Network Management Protocol (SNMP) Version 1 Agent

• Simple Network Management Protocol (SNMP) Version 2 community based Agent

• Module for Microchip TCP/IP Stack

• -Provides SNMP API for doing stuff

• -Reference: RFC 1157 (for SNMP V1)

• RFC 3416 (for SNMPv2C)

*******************************************************************

• FileName: SNMP.c

• Dependencies: UDP, ARP

• Processor: PIC18, PIC24F, PIC24H, dsPIC30F, dsPIC33F, PIC32

• Compiler: Microchip C32 v1.05 or higher

• Microchip C30 v3.12 or higher

• Microchip C18 v3.30 or higher

• HI-TECH PICC-18 PRO 9.63PL2 or higher

• Company: Microchip Technology, Inc.

• Software License Agreement

• reserved.

• Microchip licenses to you the right to use, modify, copy, and

• distribute:

• (i) the Software when embedded on a Microchip microcontroller or

• digital signal controller product ("Device") which is

• integrated into Licensee's product; or

• (ii) ONLY the Software driver source files ENC28J60.c, ENC28J60.h,

• ENCX24J600.c and ENCX24J600.h ported to a non-Microchip device

• used in conjunction with a Microchip ethernet controller for

• the sole purpose of interfacing with the ethernet controller.

Files

455

10.15 SNMP Microchip TCP/IP Stack Help

• You should refer to the license agreement accompanying this

• Software for additional information regarding your rights and

• obligations.

• THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT

• WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT

• LIMITATION, ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A

• PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL

• MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR

• CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF

• PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS

• BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE

• THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER

• SIMILAR COSTS, WHETHER ASSERTED ON THE BASIS OF CONTRACT, TORT

• (INCLUDING NEGLIGENCE), BREACH OF WARRANTY, OR OTHERWISE.

• Author Date Comment

*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

• Nilesh Rajbharti 1/9/03 Original (Rev 1.0)

• Dan Cohen 12/11/03 Removed trap support by #define if not

• required to lower code space requirements

• Amit Shirbhate 09/24/08 SNMPv2c Support, comments and function

• headers added.

• Hrisikesh Sahu 04/15/10 SNMPv2 Trap Format Support.

Files

10.15.9.5

SNMP.h

Enumerations

Name

DATA_TYPE ( see page 350)

Description

This is type COMMUNITY_TYPE.

GENERIC_TRAP_NOTIFICATION_TYPE ( see page 333)

INOUT_SNMP_PDU ( see page 417)

SNMP_ACTION ( see page 333)

This is type GENERIC_TRAP_NOTIFICATION_TYPE.

This is type INOUT_SNMP_PDU.

This is the list of SNMP action a remote NMS can perform. This inforamtion is passed to application via

callback SNMPValidateCommunity ( see page 341)().

Application should validate the action for given community string.

SNMP_ERR_STATUS ( see page 361)

VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE

( see page 333)

This is type

VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE.

456

10.15 SNMP

Functions

Microchip TCP/IP Stack Help Files

Name

_SNMPDuplexInit ( see page 347)

_SNMPGet ( see page 347)

_SNMPPut ( see page 348)

GetDataTypeInfo ( see page 355)

Description

Prepare for full duplex transfer.

Read byte from snmp udp socket rx buffer.

Copy byte to tx buffer.

Get ASN data type info.

GetNextLeaf ( see page 367)

GetOIDStringByAddr ( see page 368)

Searches for the next leaf node in the MIP tree.

Get OID string from MPFS using the node address.

GetOIDStringByID ( see page 368)

Get complete notification variable OID string from MPFS using var id.

getSnmpV2GenTrapOid ( see page 381) Resolves generic trap code to generic trap OID.

IsValidInt ( see page 369)

IsValidLength ( see page 363)

Verifies variable datatype as INT and retrieves its value.

Retrieves the packet length and actual pdu length.

Decode variable length structure.

IsValidStructure ( see page 371)

OIDLookup ( see page 372)

To search and validate whether the requested OID is in the MIB database.

This routine process the SNMPv2c Get Bulk Request.

ProcessGetBulkVar ( see page 383)

ProcessGetNextVar ( see page 384)

ProcessGetVar ( see page 385)

Retrieves next node from the MIB database.

Processes snmp Get request pdu.

ProcessSetVar ( see page 374)

ProcessSnmpv3MsgData ( see page

385)

SetErrorStatus ( see page 360)

Processes snmp Set request pdu.

This routine processes the snmpv3 request and parallely creates the response pdu.

Set snmp error status in the response pdu.

SNMPGetExactIndex ( see page 386)

SNMPGetNextIndex ( see page 340)

To search for exact index node in case of a Sequence variable.

To search for next index node in case of a Sequence variable.

SNMPGetVar ( see page 338)

Used to Get/collect OID variable information.

SNMPIdRecrdValidation ( see page 386) Used to Restrict the access dynamic and non dynamic OID string

for A perticular SNMP Version.

SNMPInit ( see page 376)

SNMPIsNotifyReady ( see page 339)

Initialize SNMP module internals.

Resolves given remoteHost IP address into MAC address.

SNMPIsValidSetLen ( see page 387)

SNMPNotify ( see page 337)

SNMPNotifyPrepare ( see page 340)

Validates the set variable data length to data type.

Creates and Sends TRAP pdu.

Collects trap notification info and send ARP to remote host.

SNMPSendTrap ( see page 336)

Prepare, validate remote node which will receive trap and send trap pdu.

457

10.15 SNMP Microchip TCP/IP Stack Help Files

SNMPSetVar ( see page 338)

This routine Set the mib variable with the requested value.

SNMPTask ( see page 377)

Snmpv3AESDecryptRxedScopedPdu ( see page 388)

Snmpv3BufferPut ( see page 390)

Polls for every snmp pdu received.

Incoming SNMPv3 scoped PDU decryption using AES decryption protocol.

Copies BYTE data to dynamically allocated memory buffer.

Snmpv3FormulateEngineID ( see page

394)

Formulates the snmpEngineID ( see page 433) for the SNMPV3

engine.

Snmpv3GetAuthEngineTime ( see page

395)

Updates the snmp engine time variable 'snmpEngineTime ( see page 434)' for the SNMPV3 engine.

Snmpv3GetBufferData ( see page 396)

Reads BYTE data from dynamically allocated memory buffer.

Snmpv3MsgProcessingModelProcessPDU

( see page 399)

This routine collects or populates the message processing model infomation from the received SNMPv3 request PDU or to the response PDU respectively.

Snmpv3Notify ( see page 400)

Snmpv3ScopedPduProcessing ( see page 402)

Creates and Sends SNMPv3 TRAP pdu.

This routine collects the scoped pdu header information from the received SNMPv3 request PDU or populates to the response PDU respectively.

Snmpv3TrapScopedpdu ( see page 403) TRAP PDU scoped pdu header construction.

Snmpv3UserSecurityModelProcessPDU

( see page 404)

This routine collects or populates the security model parametrs infomation from the received SNMPv3 request PDU or to the response PDU respectively.

AES Encryption and decryption init vector.(RFC 3826 )

Snmpv3UsmAesEncryptDecryptInitVector

( see page 404)

Snmpv3UsmOutMsgAuthenticationParam

( see page 405)

Both MD5 and SHA1 is used for the outgoing message authentication.

Validate engine ID.

Snmpv3ValidateEngineId ( see page

406)

Snmpv3ValidateSecNameAndSecLvl ( see page 406)

Vaidate security name with Security level.

Snmpv3ValidateSecurityName ( see page 407)

SNMPValidateCommunity ( see page

341)

Validate SNMPV3 user name or security name.

Validates community name for access control.

Macros

Name

_SNMPGetTxOffset ( see page 348)

_SNMPSetTxOffset ( see page 349)

AGENT_NOTIFY_PORT ( see page 349)

ASN_INT ( see page 349)

ASN_NULL ( see page 349)

ASN_OID ( see page 350)

DATA_TYPE_TABLE_SIZE ( see page 351)

GET_BULK_REQUEST ( see page 352)

GET_NEXT_REQUEST ( see page 352)

GET_REQUEST ( see page 352)

Description

This is macro _SNMPGetTxOffset.

This is macro AGENT_NOTIFY_PORT.

This is macro ASN_INT.

This is macro ASN_NULL.

This is macro ASN_OID.

This is macro GET_BULK_REQUEST.

This is macro GET_NEXT_REQUEST.

458

10.15 SNMP Microchip TCP/IP Stack Help Files

GET_RESPONSE ( see page 353)

IS_AGENT_PDU ( see page 353)

IS_ASN_INT ( see page 354)

IS_ASN_NULL ( see page 354)

IS_GET_NEXT_REQUEST ( see page 354)

IS_GET_REQUEST ( see page 354)

This is macro GET_RESPONSE.

This is macro IS_AGENT_PDU.

This is macro IS_ASN_INT.

This is macro IS_ASN_NULL.

This is macro IS_GET_NEXT_REQUEST.

This is macro IS_GET_REQUEST.

IS_GET_RESPONSE ( see page 355)

IS_OCTET_STRING ( see page 355)

This is macro IS_GET_RESPONSE.

This is macro IS_OCTET_STRING.

IS_OID ( see page 355)

IS_SET_REQUEST ( see page 356)

This is macro IS_OID.

This is macro IS_SET_REQUEST.

IS_SNMPV3_AUTH_STRUCTURE ( see page 440) This is macro IS_SNMPV3_AUTH_STRUCTURE.

IS_STRUCTURE ( see page 356)

IS_TRAP ( see page 356)

OCTET_STRING ( see page 357)

OID_MAX_LEN ( see page 342)

REPORT_RESPONSE ( see page 441)

This is macro IS_TRAP.

This is macro OCTET_STRING.

Change this to match your OID string length.

This is macro REPORT_RESPONSE.

This is macro SET_REQUEST.

SET_REQUEST ( see page 359)

SNMP_AGENT_PORT ( see page 360)

SNMP_BIB_FILE_NAME ( see page 360)

SNMP_COUNTER32 ( see page 361)

SNMP_END_OF_VAR ( see page 343)

SNMP_GAUGE32 ( see page 362)

SNMP_INDEX_INVALID ( see page 343)

SNMP_IP_ADDR ( see page 362)

SNMP_MAX_MSG_SIZE ( see page 441)

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.

This is macro SNMP_COUNTER32.

This is macro SNMP_END_OF_VAR.

This is macro SNMP_GAUGE32.

SNMP_MAX_OID_LEN_MEM_USE ( see page

442)

SNMP_NMS_PORT ( see page 362)

SNMP_NSAP_ADDR ( see page 363)

SNMP_OPAQUE ( see page 364)

This is macro SNMP_INDEX_INVALID.

This is macro SNMP_IP_ADDR.

SNMP MIN and MAX message 484 bytes in size As per

RFC 3411 snmpEngineMaxMessageSize ( see page

433) and RFC 1157 ( section 4- protocol specification )

and implementation supports more than 484 whenever feasible.

This macro will be used to avoid SNMP OID memory buffer corruption

This is macro SNMP_NMS_PORT.

This is macro SNMP_NSAP_ADDR.

This is macro SNMP_OPAQUE.

459

10.15 SNMP Microchip TCP/IP Stack Help Files

SNMP_START_OF_VAR ( see page 342)

SNMP_TIME_TICKS ( see page 364)

This is macro SNMP_START_OF_VAR.

This is macro SNMP_TIME_TICKS.

SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE

STRUCTURE ( see page 366)

This macro will be used to avoid SNMP OID memory buffer corruption

SNMP_V1 ( see page 365)

SNMP_V2C ( see page 365)

SNMP_V3 ( see page 442)

This is macro SNMP_V2C.

This is macro SNMP_V3.

TRAP ( see page 367)

This is macro TRAP.

TRAP_COMMUNITY_MAX_LEN ( see page 343)

This is macro TRAP_COMMUNITY_MAX_LEN.

TRAP_TABLE_SIZE ( see page 343)

This is macro TRAP_TABLE_SIZE.

Structures

Name

DATA_TYPE_INFO ( see page 351)

OID_INFO ( see page 358)

PDU_INFO ( see page 358)

reqVarErrStatus ( see page

359)

SNMP_NOTIFY_INFO ( see page 363)

SNMPNONMIBRECDINFO

( see page 419)

SNMPV3MSGDATA ( see page 422)

TRAP_INFO ( see page

335)

Description

This is type SNMPNONMIBRECDINFO.

SNMPv3

This is type TRAP_INFO.

Types

Name

SNMP_INDEX ( see page

342)

Description

SNMP_ID ( see page 342)

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.

This is type SNMP_INDEX.

Unions

Name

INDEX_INFO ( see page

353)

MIB_INFO ( see page 357)

Description

SNMP_STATUS ( see page

364)

SNMP_VAL ( see page 334) This is type SNMP_VAL.

Description

• SNMP Defs for Microchip TCP/IP Stack

*******************************************************************

• FileName: SNMP.h

460

10.16 SNTP Client Microchip TCP/IP Stack Help

• Dependencies: StackTsk.h

• UDP.h

• Processor: PIC18, PIC24F, PIC24H, dsPIC30F, dsPIC33F, PIC32

• Compiler: Microchip C32 v1.05 or higher

• Microchip C30 v3.12 or higher

• Microchip C18 v3.30 or higher

• HI-TECH PICC-18 PRO 9.63PL2 or higher

• Company: Microchip Technology, Inc.

• Software License Agreement

• reserved.

• Microchip licenses to you the right to use, modify, copy, and

• distribute:

• (i) the Software when embedded on a Microchip microcontroller or

• digital signal controller product ("Device") which is

• integrated into Licensee's product; or

• (ii) ONLY the Software driver source files ENC28J60.c, ENC28J60.h,

• ENCX24J600.c and ENCX24J600.h ported to a non-Microchip device

• used in conjunction with a Microchip ethernet controller for

• the sole purpose of interfacing with the ethernet controller.

• You should refer to the license agreement accompanying this

• Software for additional information regarding your rights and

• obligations.

• THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT

• WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT

• LIMITATION, ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR A

• PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL

• MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR

• CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF

• PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS

• BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE

• THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER

• SIMILAR COSTS, WHETHER ASSERTED ON THE BASIS OF CONTRACT, TORT

• (INCLUDING NEGLIGENCE), BREACH OF WARRANTY, OR OTHERWISE.

• V5.36 ---- STACK_USE_MPFS has been removed

461

10.16 SNTP Client Microchip TCP/IP Stack Help SNTP Client Stack Members

10.16

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 ( see page 462) using the internal Tick timer module.

The SNTP module is good for providing absolute time stamps. However, it should not be relied upon for measuring time differences (especially small differences). The pool of public time servers is implemented using round-robin DNS, so each update will come from a different server. Differing network delays and the fact that these servers are not verified implies that this time could be non-linear. While it is deemed reliable, it is not guaranteed to be accurate.

The Tick module provides much better accuracy (since it is driven by a hardware clock) and resolution, and should be used for measuring timeouts and other internal requirements.

Developers can change the value of NTP_SERVER ( see page 466) 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.

10.16.1

SNTP Client Public Members

Functions

Name

SNTPGetUTCSeconds ( see page 462)

Module

SNTPClient ( see page 463) Periodically checks the current time from a pool of servers.

Description

Obtains the current time from the SNTP module.

Description

The following functions and variables are available to the stack application.

10.16.1.1

SNTPGetUTCSeconds Function

File

SNTP.h

DWORD SNTPGetUTCSeconds();

Returns

The number of seconds since the Epoch. (Default 01-Jan-1970 00:00:00)

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.

Remarks

Do not use this function for time difference measurements. The Tick module is more appropriate for those requirements.

Preconditions

None

462

10.16 SNTP Client Microchip TCP/IP Stack Help SNTP Client Internal Members

10.16.2

SNTP Client Stack Members

Functions

Name Description

Module

NTP_EPOCH ( see page 466)

Description

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.

10.16.2.1

SNTPClient Function

File

SNTP.h

C void

SNTPClient();

Returns

None

Description

This function periodically checks a pool of time servers to obtain the current date/time.

Remarks

This function requires once available UDP socket while processing, but frees that socket when the SNTP module is idle.

Preconditions

UDP is initialized.

10.16.3

SNTP Client Internal Members

Macros

Name Description

Reference Epoch to use. (default: 01-Jan-1970 00:00:00)

NTP_FAST_QUERY_INTERVAL

( see page 466)

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 ( see page 466)

Defines how frequently to resynchronize the date/time (default: 10 minutes)

NTP_REPLY_TIMEOUT ( see page 466)

Defines how long to wait before assuming the query has failed

463

10.16 SNTP Client Microchip TCP/IP Stack Help SNTP Client Internal Members

NTP_SERVER ( see page 466) 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 ( see page 467)

Port for contacting NTP servers

Module

dwLastUpdateTick ( see page 465) dwSNTPSeconds ( see page 465)

Structures

Name

NTP_PACKET ( see page

464)

Description

Defines the structure of an NTP packet

Variables

Name

Description

Tick count of last update

Seconds value obtained by last update

Description

The following functions and variables are designated as internal to the SNTP Client module.

10.16.3.1

NTP_PACKET Structure

File

SNTP.c

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;

464

10.16 SNTP Client Microchip TCP/IP Stack Help

Members

struct {

BYTE mode : 3;

BYTE versionNumber : 3;

BYTE leapIndicator : 2;

} flags;

BYTE mode : 3;

BYTE versionNumber : 3;

BYTE leapIndicator : 2;

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;

Description

Defines the structure of an NTP packet

Description

Flags for the packet

NTP mode

SNTP version number

Leap second indicator

Stratum level of local clock

Poll interval

Precision (seconds to nearest power of 2)

Root delay between local machine and server

Root dispersion (maximum error)

Reference clock identifier

Reference timestamp (in seconds)

Reference timestamp (fractions)

Origination timestamp (in seconds)

Origination timestamp (fractions)

Time at which request arrived at sender (seconds)

Time at which request arrived at sender (fractions)

Time at which request left sender (seconds)

Time at which request left sender (fractions)

SNTP Client Internal Members

10.16.3.2

dwLastUpdateTick Variable

File

SNTP.c

DWORD dwLastUpdateTick = 0;

Description

Tick count of last update

10.16.3.3

dwSNTPSeconds Variable

File

SNTP.c

DWORD dwSNTPSeconds = 0;

Description

Seconds value obtained by last update

465

10.16 SNTP Client Microchip TCP/IP Stack Help SNTP Client Internal Members

10.16.3.4

NTP_EPOCH Macro

File

SNTP.c

#define

NTP_EPOCH (86400ul * (365ul * 70ul + 17ul))

Description

Reference Epoch to use. (default: 01-Jan-1970 00:00:00)

10.16.3.5

NTP_FAST_QUERY_INTERVAL Macro

File

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

10.16.3.6

NTP_QUERY_INTERVAL Macro

File

SNTP.c

#define

NTP_QUERY_INTERVAL (10ull*60ull * TICK_SECOND)

Description

Defines how frequently to resynchronize the date/time (default: 10 minutes)

10.16.3.7

NTP_REPLY_TIMEOUT Macro

File

SNTP.c

#define

NTP_REPLY_TIMEOUT (6ul*TICK_SECOND)

Description

Defines how long to wait before assuming the query has failed

10.16.3.8

NTP_SERVER Macro

File

SNTP.c

466

10.17 SSL Microchip TCP/IP Stack Help

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

10.16.3.9

NTP_SERVER_PORT Macro

File

SNTP.c

#define

NTP_SERVER_PORT (123ul)

Description

Port for contacting NTP servers

10.17

SSL

Files

Name

(SSL_RSA_CLIENT_SIZE ( see page 476))

Description

This is file SSLClientSize.h.

Description

The SSL module adds encryption support to the TCP layer by implementing the SSLv3 protocol. This protocol is the standard for secure communications across the Internet, and prevents snooping or tampering of data as it travels across an untrusted network. This implementation of SSL supports the RSA asymmetric encryption protocol and the ARCFOUR symmetric encryption protocol.

Compiler

C18

C30

C32

SSL Server Maximum RSA key length

(SSL_RSA_KEY_SIZE ( see page 475))

1024

2048

SSL Client Maximum RSA key length

1024

2048

Previous versions of the MLA software distribution required that files containing cryptographic algorithm implementations be distributed separately to comply with U.S. Export Controls. In this version, the cryptographic modules are included with the

TCP/IP Stack.

SSL Client Support

An SSL client can be initiated by first opening a TCP connection, then calling TCPStartSSLSession to initiate the SSL handshake process. The handshake uses the public key from the certificate provided by the server. Key lengths up to 1024 bits are supported on all processors; key lengths up to 2048 bits are supported on PIC32 microcontrollers. The

SSL_RSA_CLIENT_SIZE ( see page 476)

macro in

Once the handshake has started, call TCPSSLIsHandshaking ( see page 473) until it returns FALSE. This will indicate that

sets the maximum certificate key length that your client should process.

#define

SSL_RSA_CLIENT_SIZE (1024ul)

// Size of Encryption Buffer (must be larger

467

10.17 SSL Microchip TCP/IP Stack Help Generating Server Certificates

than key size)

the handshake has completed and all traffic is now secured using 128-bit ARCFOUR encryption. If the handshake fails for any reason, the TCP connection will automatically be terminated as required by the SSL protocol specification.

For faster performance, the SSL module caches security parameters for the most recently made connections. This allows quick reconnections to the same node without the computational expense of another RSA handshake. By default, the two most recent connections are cached, but this can be modified in TCPIPConfig.h.

SSL client support is already enabled for SMTP. When STACK_USE_SSL_CLIENT is defined, the SMTP module

automatically adds a field to SMTPClient ( see page 309) called UseSSL. That field controls whether or not the SMTP

client module will attempt to make an SSL connection before transmitting any data.

Note that TCP sockets using SSL may required an increase in TX/RX buffer size to support SSL. You can adjust the size of your sockets using the TCP/IP Configuration Utility included with the stack.

SSL Server Support

To initiate an SSL server, first open a TCP socket for listening using TCPOpen ( see page 547). Then call

TCPAddSSLListener ( see page 472) to listen ( see page 180) for incoming SSL connections on an alternate port. This allows a single socket to share application-level resources and listen ( see page 180) for connections on two different

ports. Connections occurring on the originally opened port will proceed unsecured, while connections on the SSL port will first complete an SSL handshake to secure the data.

If you application will not accept ( see page 174) unsecured traffic, simply open a non-secured socket on a free port

number, then verify that each incoming connection is secured (not on that port) by calling TCPIsSSL ( see page 474).

SSL server support is automatically enabled for HTTP2 when STACK_USE_SSL_SERVER is defined. By default, the

HTTP2 module will then listen ( see page 180) for unsecured traffic on port 80 and secured connections on port 443.

This SSL server implementation supports key lengths up to 1024 bits on most PIC microcontrollers, and 2048 bits on PIC32 microcontrollers. The

SSL_RSA_KEY_SIZE ( see page 475)

macro in TCPIPConfig.h sets the server certificate key length.

// Bits in SSL RSA key. This parameter is used for SSL sever

// connections only.

#define

SSL_RSA_KEY_SIZE (512ul)

Note that TCP sockets using SSL may required an increase in TX/RX buffer size to support SSL. You can adjust the size of your sockets using the TCP/IP Configuration Utility included with the stack.

Limitations

SSL was designed for desktop PCs with faster processors and significantly more resources than are available on an embedded platform. A few compromises must be made in order to use SSL in a less resource-intensive manner.

The SSL client module does not perform any validation or verification of certificates. Doing so would require many root certificates to be stored locally for verification, which is not feasible for memory-limited parts. This does not compromise security once the connection has been established, but does not provide complete security against man-in-the-middle attacks. (This sort of attack is uncommon and would be difficult to execute.)

Neither the SSL client nor the server can completely verify MACs before processing data. SSL records include a signature to

verify that messages were not modified in transit. This Message Authentication ( see page 91) 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.

468

10.17 SSL Microchip TCP/IP Stack Help Generating Server Certificates

10.17.1

Generating Server Certificates

Module

10. This information must be copied verbatim into the SSL_CERT ( see page 499)[] array. Note that this is binary data (not

Description

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

915E3E5BDB6FAB0233B5DFA2E4 08 1D F7 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

469

10.17 SSL Microchip TCP/IP Stack Help Generating Server Certificates

};

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:

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,

470

10.17 SSL Microchip TCP/IP Stack Help

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 ( see page 499) variable to contain the correct value.

SSL Public Members

10.17.2

SSL Public Members

Enumerations

Name Description

SSL_SUPPLEMENTARY_DATA_TYPES

( see page 475)

This is type SSL_SUPPLEMENTARY_DATA_TYPES.

Functions

Name

TCPAddSSLListener ( see page 472)

TCPSSLIsHandshaking ( see page 473)

Description

Listens for SSL connection on a specific port.

Determines if an SSL session is still handshaking.

TCPStartSSLClient ( see page 473)

Begins an SSL client session.

TCPIsSSL ( see page 474)

Determines if a TCP connection is secured with SSL.

SSLStartSession ( see page 474)

Begins a new SSL session for the given TCP connection.

Macros

Name

SSL_INVALID_ID ( see page 472)

Description

Identifier for invalid SSL allocations

471

10.17 SSL Microchip TCP/IP Stack Help SSL Public Members

SSL_RSA_KEY_SIZE ( see page 475)

SSL_RSA_CLIENT_SIZE ( see page 476)

Bits in SSL RSA key. This parameter is used for SSL sever connections only.

The only valid value is 512 bits (768 and 1024 bits do not work at this time).

Note, however, that SSL client operations do currently work up to 1024 bit RSA key length.

Size of Encryption Buffer (must be larger than key size)

Module

SSL_PKEY_INFO ( see page 475)

Structures

Name

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.

Description

The following functions and variables are available to the stack application.

10.17.2.1

SSL_INVALID_ID Macro

File

SSL.h

#define

SSL_INVALID_ID (0xFFu)

// Identifier for invalid SSL allocations

Description

Identifier for invalid SSL allocations

10.17.2.2

TCPAddSSLListener Function

File

TCP.h

BOOL TCPAddSSLListener(

SSL port to listen ( see page 180) on

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

hTCP port

Return Values

TRUE

Description

TCP connection to secure

Description

SSL port was added.

472

10.17 SSL

FALSE

Microchip TCP/IP Stack Help

The socket was not a listening socket.

SSL Public Members

10.17.2.3

TCPSSLIsHandshaking Function

File

TCP.h

BOOL TCPSSLIsHandshaking(

Call this function after calling TCPStartSSLClient ( see page 473) until FALSE is returned. Then your application may

);

Description

continue with its normal data transfer (which is now secured).

Preconditions

TCP is initialized and hTCP is connected.

Parameters

hTCP

Return Values

TRUE

FALSE

Description

TCP connection to check

Description

SSL handshake is still progressing

SSL handshake has completed

10.17.2.4

TCPStartSSLClient Function

File

TCP.h

BOOL TCPStartSSLClient(

BYTE* host

);

Description

This function escalates the current connection to an SSL secured connection by initiating an SSL client handshake.

Remarks

The host parameter is currently ignored and is not validated.

Preconditions

TCP is initialized and hTCP is already connected.

Parameters

hTCP host

Description

TCP connection to secure

Expected host name on certificate (currently ignored)

473

10.17 SSL

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help

Description

an SSL connection was initiated

Insufficient SSL resources (stubs) were available

10.17.2.5

TCPIsSSL Function

File

TCP.h

BOOL TCPIsSSL(

);

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

hTCP

Return Values

TRUE

FALSE

Description

TCP connection to check

Description

Connection is secured via SSL

Connection is not secured

10.17.2.6

SSLStartSession Function

File

SSL.h

BYTE SSLStartSession(

SSL_INVALID_ID ( see page 472)

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

hTCP buffer supDataType

Description

the socket to begin the SSL connection on pointer to a supplementary data buffer type of supplementary data to store

SSL Public Members

474

10.17 SSL

Return Values

others

Microchip TCP/IP Stack Help

Description

insufficient SSL resources to start a new connection the allocated SSL stub ID

SSL Public Members

10.17.2.7

SSL_SUPPLEMENTARY_DATA_TYPES Enumeration

File

SSL.h

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.

10.17.2.8

SSL_PKEY_INFO Structure

File

SSL.h

C typedef struct

{

WORD pub_size_bytes;

BYTE pub_key[SSL_RSA_CLIENT_SIZE/8];

BYTE pub_e[3];

BYTE pub_guid;

} SSL_PKEY_INFO;

Members

BYTE pub_guid;

Description

This is used as a TCP_SOCKET ( see page 558) which is a BYTE

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.

10.17.2.9

SSL_RSA_KEY_SIZE Macro

File

TCPIP MRF24W.h

#define

SSL_RSA_KEY_SIZE (512ul)

Description

Bits in SSL RSA key. This parameter is used for SSL sever connections only. The only valid value is 512 bits (768 and 1024 bits do not work at this time). Note, however, that SSL client operations do currently work up to 1024 bit RSA key length.

475

10.17 SSL Microchip TCP/IP Stack Help SSL Stack Members

10.17.2.10

SSL_RSA_CLIENT_SIZE Macro

File

TCPRequestSSLMessage ( see page 478)

#define

SSL_RSA_CLIENT_SIZE (1024ul)

// Size of Encryption Buffer (must be larger than key size)

Description

Size of Encryption Buffer (must be larger than key size)

10.17.3

SSL Stack Members

Enumerations

Name

SSL_STATE ( see page

477)

Description

This is type SSL_STATE.

Functions

Name

SSLInit ( see page 477)

SSLPeriodic ( see page

477)

Description

Initializes the SSL engine.

Performs any periodic tasks for the SSL module.

Requests an SSL message to be transmitted.

TCPSSLGetPendingTxSize

( see page 478)

Determines how many bytes are pending for a future SSL record.

TCPSSLHandleIncoming ( see page 479)

Hands newly arrive TCP data to the SSL module for processing.

TCPSSLHandshakeComplete

( see page 479)

Clears the SSL handshake flag.

TCPSSLInPlaceMACEncrypt

( see page 480)

Encrypts and MACs data in place in the TCP TX buffer.

TCPSSLPutRecordHeader ( see page 480)

Writes an SSL record header and sends an SSL record.

TCPStartSSLServer ( see page 481)

Begins an SSL server session.

Macros

Name Description

SSL_MIN_SESSION_LIFETIME ( see page 481)

Minimum lifetime for SSL Sessions Sessions cannot be reallocated until this much time has elapsed

SSL_RSA_LIFETIME_EXTENSION

( see page 482)

Lifetime extension for RSA operations Sessions lifetime is extended by this amount when an RSA calculation is made

Module

Description

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.

476

10.17 SSL Microchip TCP/IP Stack Help

10.17.3.1

SSL_STATE Enumeration

File

TCP.h

C typedef enum

{

SSL_NONE = 0,

SSL_HANDSHAKING,

SSL_ESTABLISHED,

SSL_CLOSED

} SSL_STATE;

Members

SSL_NONE = 0

SSL_HANDSHAKING

SSL_ESTABLISHED

SSL_CLOSED

Description

This is type SSL_STATE.

Description

No security is enabled

Handshake is progressing (no application data allowed)

Connection is established and secured

Connection has been closed (no applicaiton data is allowed)

10.17.3.2

SSLInit Function

File

SSL.h

C void

SSLInit();

Returns

None

Description

Initializes the SSL engine.

Remarks

This function is called only one during lifetime of the application.

Preconditions

None

Section

Function Prototypes

10.17.3.3

SSLPeriodic Function

File

SSL.h

C void

SSLPeriodic(

SSL Stack Members

477

10.17 SSL Microchip TCP/IP Stack Help

BYTE sslStubID

);

Returns

None

Description

This function performs periodic tasks for the SSL module. This includes processing for RSA operations.

Preconditions

SSL has already been initialized.

Parameters

hTCP id

Description

the socket for which to perform periodic functions the SSL stub to use

SSL Stack Members

10.17.3.4

TCPRequestSSLMessage Function

File

TCP.h

BOOL TCPRequestSSLMessage(

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

hTCP msg

Return Values

TRUE

FALSE

Description

TCP connection to use

One of the SSL_MESSAGE types to transmit.

Description

The message was requested.

Another message is already pending transmission.

10.17.3.5

TCPSSLGetPendingTxSize Function

File

TCP.h

WORD TCPSSLGetPendingTxSize(

);

478

10.17 SSL Microchip TCP/IP Stack Help

Returns

None

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

hTCP

Description

TCP connection to check

SSL Stack Members

10.17.3.6

TCPSSLHandleIncoming Function

File

TCP.h

C void

TCPSSLHandleIncoming(

);

Returns

None

Description

This function processes incoming TCP data as an SSL record and performs any necessary repositioning and decrypting.

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Preconditions

TCP is initialized, and hTCP is connected with an active SSL session.

Parameters

hTCP

Description

TCP connection to handle incoming data on

10.17.3.7

TCPSSLHandshakeComplete Function

File

TCP.h

C void

TCPSSLHandshakeComplete(

);

Returns

None

Description

This function clears the flag indicating that an SSL handshake is complete.

479

10.17 SSL Microchip TCP/IP Stack Help

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Preconditions

TCP is initialized and hTCP is connected.

Parameters

hTCP

Description

TCP connection to set

SSL Stack Members

10.17.3.8

TCPSSLInPlaceMACEncrypt Function

File

TCP.h

C void

TCPSSLInPlaceMACEncrypt(

ARCFOUR_CTX* ctx,

BYTE* MACSecret,

WORD len

);

Returns

None

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.

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Preconditions

TCP is initialized, hTCP is connected, and ctx's Sbox is loaded.

Parameters

hTCP ctx

MACSecret len

Description

TCP connection to encrypt in

ARCFOUR encryption context to use

MAC encryption secret to use

Number of bytes to crypt

10.17.3.9

TCPSSLPutRecordHeader Function

File

TCP.h

C void

TCPSSLPutRecordHeader(

BYTE* hdr,

BOOL recDone

);

480

10.17 SSL Microchip TCP/IP Stack Help SSL Stack Members

Returns

None

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.

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Preconditions

TCP is initialized, and hTCP is connected with an active SSL session.

Parameters

hTCP hdr recDone

Description

TCP connection to write the header and transmit with

Record header (5 bytes) to send or NULL to just move the pointerctx

TRUE if the record is done, FALSE otherwise

10.17.3.10

TCPStartSSLServer Function

File

TCP.h

BOOL TCPStartSSLServer(

SSL_MIN_SESSION_LIFETIME (1*TICK_SECOND)

);

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

hTCP

Return Values

TRUE

FALSE

Description

TCP connection to secure

Description

an SSL connection was initiated

Insufficient SSL resources (stubs) were available

10.17.3.11

SSL_MIN_SESSION_LIFETIME Macro

File

SSL.h

481

10.17 SSL Microchip TCP/IP Stack Help

#define

Description

Minimum lifetime for SSL Sessions Sessions cannot be reallocated until this much time has elapsed

SSL Internal Members

10.17.3.12

SSL_RSA_LIFETIME_EXTENSION Macro

File

SSL.h

#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

10.17.4

SSL Internal Members

Enumerations

Name Description

SM_SSL_RX_SERVER_HELLO

( see page 496)

State machine for SSLRxServerHello ( see page 518)

Describes the two types of Alert records

SSL_ALERT_LEVEL ( see page 496)

SSL_MESSAGES ( see page

501)

SSL_SESSION_TYPE ( see page 504)

Describes the types of SSL messages (handshake and alerts)

SSL Session Type Enumeration

Functions

Name

CalculateFinishedHash ( see page 487)

GenerateHashRounds ( see page 488)

GenerateSessionKeys ( see page 488)

HSEnd ( see page 489)

Description

Calculates the handshake hash over the data. hashID can be either MD5 or

SHA-1, and this function will calculate accordingly.

Generates hash rounds to find either the Master Secret or the Key Block.

Generates the session write keys and MAC secrets

HSGet ( see page 489)

Hashes ( see page 207) the message contents into the Handshake hash

structures and begins a new handshake hash.

Reads data from socket, transparently hashing it into the handshake hashes.

482

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

HSGetArray ( see page 490)

• Function: static WORD HSGetArray(TCP_SOCKET ( see page 558) 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 ( see page 490) Reads data from socket, transparently hashing it into the handshake hashes.

HSPut ( see page 491)

Writes data to socket, transparently hashing it into the handshake hashes.

HSPutArray ( see page 491)

• Function: static WORD HSPutArray(TCP_SOCKET ( see page 558) 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 ( see page 492)

This is function HSPutROMArray.

HSPutWord ( see page 492) Writes data to socket, transparently hashing it into the handshake hashes.

HSStart ( see page 493)

Sets up the buffer to store data for handshake hash tracking

LoadOffChip ( see page

495)

Copies data from Ethernet RAM to local RAM

483

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

SaveOffChip ( see page

495)

SSLBufferAlloc ( see page

507)

SSLBufferFree ( see page

507)

SSLBufferSync ( see page

508)

Copies data in PIC RAM to the Ethernet RAM

Allocates a buffer for use.

Specified buffer is released

Specified buffer is loaded to RAM. Only loads if necessary, and saves any current buffer before switching.

Allocates a hash for use.

SSLHashAlloc ( see page

509)

SSLHashFree ( see page

510)

SSLHashSync ( see page

510)

Specified hash is released

SSLKeysSync ( see page

511)

SSLMACAdd ( see page

512)

SSLMACBegin ( see page

512)

SSLMACCalc ( see page

512)

Specified hash is loaded to RAM. Only loads if necessary, and saves any current hash before switching.

Specified key set is loaded to RAM. Only loads if necessary, and saves any current key set before switching.

This is function SSLMACAdd.

This is function SSLMACBegin.

This is function SSLMACCalc.

SSLRSAOperation ( see page 513)

Pauses connection processing until RSA calculation is complete.

SSLRxAlert ( see page 513) Receives an alert message and decides what to do

SSLRxAntiqueClientHello ( see page 514)

Receives the SSLv2 ClientHello message, initiating a new SSL session with a client

SSLRxCCS ( see page 514) Receives a ChangeCipherSpec from the remote server

SSLRxClientHello ( see page 515)

Receives the ClientHello message, initiating a new SSL session with a client

Receives the ClientKeyExchange message and begins the decryption process.

SSLRxClientKeyExchange

( see page 516)

SSLRxFinished ( see page

516)

Receives the Finished message from remote node

Receives a handshake message.

SSLRxHandshake ( see page 517)

SSLRxRecord ( see page

517)

SSLRxServerCertificate ( see page 518)

Receives an SSL record.

Receives ServerCertificate from the remote server, locates the public key information, and executes RSA operation.

Receives the ServerHello from the remote server

SSLRxServerHello ( see page 518)

SSLSessionMatchID ( see page 519)

SSLSessionMatchIP ( see page 520)

Locates a cached SSL session for reuse. Syncs found session into RAM.

Locates a cached SSL session for reuse

SSLSessionNew ( see page 520)

SSLSessionSync ( see page 521)

SSLStartPartialRecord ( see page 522)

SSLStubAlloc ( see page

523)

Finds space for a new SSL session

Specified session is loaded to RAM. Only loads if necessary, and saves any current session before switching if it has been updated.

Begins a long SSL record.

Allocates a stub for use.

484

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

SSLStubFree ( see page

523)

SSLStubSync ( see page

524)

SSLTerminate ( see page

525)

SSLTxCCSFin ( see page

525)

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 ( see page 526)

SSLTxClientKeyExchange ( see page 526)

SSLTxMessage ( see page

527)

Transmits the ClientHello message to initiate a new SSL session with the server.

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.

Transmits an SSL message.

Transmits an SSL record.

SSLTxRecord ( see page

527)

SSLTxServerCertificate ( see page 528)

SSLTxServerHello ( see page 528)

SSLTxServerHelloDone ( see page 529)

Specified stub is released

Specified stub is loaded to RAM. Only loads if necessary, and saves any current stub before switching.

Terminates an SSL connection and releases allocated resources.

Transmits the Certificate message with the server's specified public key certificate.

Transmits the ServerHello message.

Transmits the ServerHelloDone message.

Macros

Name Description

RESERVED_SSL_MEMORY ( see page 494)

Total space needed by all SSL storage requirements

SSL_ALERT ( see page 496)

SSL_APPLICATION ( see page 497)

Protocol code for Alert records

Protocol code for Application data records

SSL_BASE_BUFFER_ADDR ( see page 497)

Base address for SSL buffers

SSL_BASE_HASH_ADDR ( see page 497)

Base address for SSL hashes

SSL_BASE_KEYS_ADDR ( see page 497)

Base address for SSL keys

SSL_BASE_SESSION_ADDR ( see page 498)

Base address for SSL sessions

SSL_BASE_STUB_ADDR ( see page 498)

Base address for SSL stubs

SSL_BUFFER_SIZE ( see page 498)

SSL_BUFFER_SPACE ( see page 499)

Amount of space needed by a single SSL buffer

Amount of space needed by all SSL buffer

SSL_CHANGE_CIPHER_SPEC ( see page 499) Protocol code for Change Cipher Spec records

SSL_HANDSHAKE ( see page 500)

SSL_HASH_SIZE ( see page 500)

SSL_HASH_SPACE ( see page 500)

Protocol code for Handshake records

Amount of space needed by a single SSL hash

Amount of space needed by all SSL hash

485

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

SSL_KEYS_SIZE ( see page 501)

SSL_KEYS_SPACE ( see page 501)

Amount of space needed by a single SSL key

Amount of space needed by all SSL key

Module

SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5

Structures

( see page 502)

This is macro

SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5.

This is macro SSL_RSA_WITH_ARCFOUR_128_MD5.

SSL_RSA_WITH_ARCFOUR_128_MD5 ( see page 502)

SSL_SESSION_SIZE ( see page 503)

Amount of space needed by a single SSL session

SSL_SESSION_SPACE ( see page 503)

SSL_STUB_SIZE ( see page 506)

SSL_STUB_SPACE ( see page 506)

SSL_VERSION ( see page 506)

Amount of space needed by all SSL session

Amount of space needed by a single SSL stub

Amount of space needed by all SSL stubs

SSL version number

SSL_VERSION_HI ( see page 506)

SSL_VERSION_LO ( see page 506)

SSLFinishPartialRecord ( see page 508)

SSLFlushPartialRecord ( see page 509)

SSLSessionUpdated ( see page 522)

SSL version number (high byte)

SSL version number (low byte)

This is macro SSLFinishPartialRecord.

This is macro SSLFlushPartialRecord.

This is macro SSLSessionUpdated.

Name Description

SSL_KEYS ( see page 500) 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 ( see page

503)

Storage space for SSL Session identifiers. (The SessionID and MasterSecret)

SSL_SESSION_STUB ( see page 504)

Stub value for an SSL_SESSION ( see page 503). 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 ( see page 504) Memory holder for general information associated with an SSL connections.

Unions

Name

SSL_BUFFER ( see page

498)

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.

Variables

Name

isBufferUsed ( see page

493)

Description

Indicates which buffers are in use

isHashUsed ( see page 494) Indicates which hashes are in use isStubUsed ( see page 494) Indicates which stubs are in use masks ( see page 494) ptrHS ( see page 494)

Masks for each bit in the is*Used variables

Used in buffering handshake results

SSL_CERT ( see page 499) RSA public certificate data ?

486

10.17 SSL Microchip TCP/IP Stack Help

SSL_CERT_LEN ( see page 499)

RSA public certificate length ?

sslBufferID ( see page 508)

Which buffer is loaded

sslHash ( see page 509)

Hash storage

sslHashID ( see page 510)

Which hash is loaded

sslKeys ( see page 511)

The current SSL session

sslKeysID ( see page 511)

Which SSL_KEYS ( see page 500) are loaded

sslRSAStubID ( see page

513)

Which stub is using RSA, if any

sslSession ( see page 519)

Current session data

sslSessionID ( see page

519)

Which session is loaded

sslSessionStubs ( see page

521)

8 byte session stubs

sslSessionUpdated ( see page 522)

Whether or not it has been updated

sslStub ( see page 523)

The current SSL stub

sslStubID ( see page 524)

Which SSL_STUB ( see page 504) is loaded

Description

The following functions and variables are designated as internal to the SSL module.

SSL Internal Members

10.17.4.1

CalculateFinishedHash Function

File

SSL.c

C static void

CalculateFinishedHash(

BYTE hashID,

BOOL fromClient,

BYTE * result

);

Side Effects

None

Returns

None

Description

Calculates the handshake hash over the data. hashID can be either MD5 or SHA-1, and this function will calculate accordingly.

Remarks

None

Preconditions

hashID has all handshake data hashed so far and the current session is synced in.

Parameters

hashID fromClient result

Description

the hash sum to use

TRUE if client is sender where to store results

487

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.2

GenerateHashRounds Function

File

SSL.c

C static void

GenerateHashRounds(

BYTE num,

BYTE* rand1,

BYTE* rand2

);

Side Effects

Destroys the SSL Buffer space

Returns

None

Description

Generates hash rounds to find either the Master Secret or the Key Block.

Remarks

This function will overflow the buffer after 7 rounds, but in practice num = 3 or num = 4.

Preconditions

The SSL buffer is allocated for temporary usage and the data to run rounds on is in sslSession.masterSecret

Parameters

num rand1 rand2

Description

how many rounds to compute the first random data block to use the second random data block to use

10.17.4.3

GenerateSessionKeys Function

File

SSL.c

C static void

GenerateSessionKeys();

Side Effects

Destroys the SSL Buffer Space

Returns

None

Description

Generates the session write keys and MAC secrets

Remarks

None

Preconditions

The SSL buffer is allocated for temporary usage, session keys are synced, and the TX and RX buffers are allocated for

488

10.17 SSL

S-boxes.

Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.4

HSEnd Function

File

SSL.c

C static void

HSEnd();

Side Effects

None

Returns

None

Description

Hashes ( see page 207) the message contents into the Handshake hash structures and begins a new handshake hash.

Remarks

None

Preconditions

None

10.17.4.5

HSGet Function

File

SSL.c

C static

WORD HSGet(

BYTE * b

);

Side Effects

None

Returns

Number of bytes read

Description

Reads data from socket, transparently hashing it into the handshake hashes.

Remarks

None

Preconditions

None

Parameters

skt b

Description

socket to read data from byte to read into

489

10.17 SSL Microchip TCP/IP Stack Help

10.17.4.6

HSGetArray Function

File

SSL.c

C static

WORD HSGetArray(

• Function: static WORD HSGetArray(TCP_SOCKET ( see page 558) skt, BYTE *data, WORD len)

BYTE * data,

WORD len

);

Description

• 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

10.17.4.7

HSGetWord Function

File

SSL.c

C static

WORD HSGetWord(

WORD * w

);

Side Effects

None

Returns

Number of bytes read

Description

Reads data from socket, transparently hashing it into the handshake hashes.

SSL Internal Members

490

10.17 SSL

Remarks

None

Preconditions

None

Parameters

skt w

Microchip TCP/IP Stack Help

Description

socket to read data from word to read into

10.17.4.8

HSPut Function

File

SSL.c

C static

WORD HSPut(

BYTE b

);

Side Effects

None

Returns

Number of bytes written

Description

Writes data to socket, transparently hashing it into the handshake hashes.

Remarks

None

Preconditions

None

Parameters

skt b

Description

socket to write data to byte to write

10.17.4.9

HSPutArray Function

File

SSL.c

C static

WORD HSPutArray(

• Function: static WORD HSPutArray(TCP_SOCKET ( see page 558) skt, BYTE *data, BYTE len)

BYTE * data,

WORD len

);

SSL Internal Members

491

10.17 SSL Microchip TCP/IP Stack Help

Description

• 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

SSL Internal Members

10.17.4.10

HSPutROMArray Function

File

SSL.c

C static

WORD HSPutROMArray(

ROM BYTE * data,

WORD len

);

Description

This is function HSPutROMArray.

10.17.4.11

HSPutWord Function

File

SSL.c

C static

WORD HSPutWord(

RESERVED_SSL_MEMORY ((DWORD)(SSL_STUB_SPACE + SSL_KEYS_SPACE + SSL_HASH_SPACE +

WORD w

);

Side Effects

None

Returns

Number of bytes written

492

10.17 SSL Microchip TCP/IP Stack Help

Description

Writes data to socket, transparently hashing it into the handshake hashes.

Remarks

None

Preconditions

None

Parameters

skt w

Description

socket to write data to word to write

10.17.4.12

HSStart Function

File

SSL.c

C static void

HSStart();

Side Effects

None

Returns

None

Description

Sets up the buffer to store data for handshake hash tracking

Remarks

None

Preconditions

None

Section

Handshake Hash and I/O Functions

10.17.4.13

isBufferUsed Variable

File

SSL.c

WORD isBufferUsed;

Description

Indicates which buffers are in use

SSL Internal Members

493

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.14

isHashUsed Variable

File

SSL.c

WORD isHashUsed;

Description

Indicates which hashes are in use

10.17.4.15

isStubUsed Variable

File

SSL.c

WORD isStubUsed;

Description

Indicates which stubs are in use

10.17.4.16

masks Variable

File

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

10.17.4.17

ptrHS Variable

File

SSL.c

BYTE * ptrHS;

Description

Used in buffering handshake results

10.17.4.18

RESERVED_SSL_MEMORY Macro

File

SSL.h

494

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

#define

SSL_BUFFER_SPACE + SSL_SESSION_SPACE))

Description

Total space needed by all SSL storage requirements

10.17.4.19

LoadOffChip Function

File

SSL.c

C static void

LoadOffChip(

BYTE * ramAddr,

PTR_BASE ethAddr,

WORD len

);

Side Effects

None

Returns

None

Description

Copies data from Ethernet RAM to local RAM

Remarks

None

Preconditions

None

Parameters

ramAddr ethAddr len

Description

destination address in RAM source address in Ethernet RAM number of bytes to copy

10.17.4.20

SaveOffChip Function

File

SSL.c

C static void

SaveOffChip(

BYTE * ramAddr,

PTR_BASE ethAddr,

WORD len

);

Side Effects

None

495

10.17 SSL Microchip TCP/IP Stack Help

Returns

None

Description

Copies data in PIC RAM to the Ethernet RAM

Remarks

None

Preconditions

None

Parameters

ramAddr ethAddr len

Description

source address in RAM destination address in Ethernet RAM number of bytes to copy

10.17.4.21

SM_SSL_RX_SERVER_HELLO Enumeration

File

SSL.h

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 ( see page 518)

SSL Internal Members

10.17.4.22

SSL_ALERT Macro

File

SSL.h

#define

SSL_ALERT 21u

// Protocol code for Alert records

Description

Protocol code for Alert records

10.17.4.23

SSL_ALERT_LEVEL Enumeration

File

SSL.h

C typedef enum

{

496

10.17 SSL

SSL_ALERT_WARNING = 1u,

SSL_ALERT_FATAL = 2u

} SSL_ALERT_LEVEL;

Members

SSL_ALERT_WARNING = 1u

SSL_ALERT_FATAL = 2u

Description

Describes the two types of Alert records

Microchip TCP/IP Stack Help

Description

Alert message is a warning (session can be resumed)

Alert message is fatal (session is non-resumable)

SSL Internal Members

10.17.4.24

SSL_APPLICATION Macro

File

SSL.h

#define

SSL_APPLICATION 23u

// Protocol code for Application data records

Description

Protocol code for Application data records

10.17.4.25

SSL_BASE_BUFFER_ADDR Macro

File

SSL.c

#define

SSL_BASE_BUFFER_ADDR (BASE_SSLB_ADDR + SSL_STUB_SPACE + SSL_KEYS_SPACE +

SSL_HASH_SPACE)

Description

Base address for SSL buffers

10.17.4.26

SSL_BASE_HASH_ADDR Macro

File

SSL.c

#define

SSL_BASE_HASH_ADDR (BASE_SSLB_ADDR + SSL_STUB_SPACE + SSL_KEYS_SPACE)

Description

Base address for SSL hashes

10.17.4.27

SSL_BASE_KEYS_ADDR Macro

File

SSL.c

#define

SSL_BASE_KEYS_ADDR (BASE_SSLB_ADDR + SSL_STUB_SPACE)

497

10.17 SSL

Description

Base address for SSL keys

Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.28

SSL_BASE_SESSION_ADDR Macro

File

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

10.17.4.29

SSL_BASE_STUB_ADDR Macro

File

SSL.c

#define

SSL_BASE_STUB_ADDR (BASE_SSLB_ADDR)

Description

Base address for SSL stubs

10.17.4.30

SSL_BUFFER Union

File

SSL.h

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.

10.17.4.31

SSL_BUFFER_SIZE Macro

File

SSL.h

#define

SSL_BUFFER_SIZE ((DWORD)

sizeof

(SSL_BUFFER))

// Amount of space

498

10.17 SSL Microchip TCP/IP Stack Help

needed by a single SSL buffer

Description

Amount of space needed by a single SSL buffer

SSL Internal Members

10.17.4.32

SSL_BUFFER_SPACE Macro

File

SSL.h

#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

10.17.4.33

SSL_CERT Variable

File

SSL.c

ROM BYTE SSL_CERT[];

Description

RSA public certificate data ?

10.17.4.34

SSL_CERT_LEN Variable

File

SSL.c

ROM WORD SSL_CERT_LEN;

Description

RSA public certificate length ?

10.17.4.35

SSL_CHANGE_CIPHER_SPEC Macro

File

SSL.h

#define

SSL_CHANGE_CIPHER_SPEC 20u

// Protocol code for Change Cipher Spec records

Description

Protocol code for Change Cipher Spec records

499

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.36

SSL_HANDSHAKE Macro

File

SSL.h

#define

SSL_HANDSHAKE 22u

// Protocol code for Handshake records

Description

Protocol code for Handshake records

10.17.4.37

SSL_HASH_SIZE Macro

File

SSL.h

#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

10.17.4.38

SSL_HASH_SPACE Macro

File

SSL.h

#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

10.17.4.39

SSL_KEYS Structure

File

SSL.h

C typedef struct

{

union

{

struct

{

BYTE MACSecret[16];

DWORD sequence;

ARCFOUR_CTX cryptCtx;

BYTE reserved[6];

} app;

BYTE random[32];

} Local;

union

{

struct

{

BYTE MACSecret[16];

DWORD sequence;

500

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

ARCFOUR_CTX cryptCtx;

BYTE reserved[6];

} app;

BYTE random[32];

} Remote;

} SSL_KEYS;

Members

BYTE MACSecret[16];

DWORD sequence;

ARCFOUR_CTX cryptCtx;

BYTE reserved[6];

BYTE random[32];

BYTE MACSecret[16];

DWORD sequence;

ARCFOUR_CTX cryptCtx;

BYTE reserved[6];

BYTE random[32];

Description

Server's MAC write secret

Server's write sequence number

Server's write encryption context

Future expansion

Server.random value

Client's MAC write secret

Client's write sequence number

Client's write encryption context

Future expansion

Client.random value

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.

10.17.4.40

SSL_KEYS_SIZE Macro

File

SSL.h

#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

10.17.4.41

SSL_KEYS_SPACE Macro

File

SSL.h

#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

10.17.4.42

SSL_MESSAGES Enumeration

File

SSL.h

501

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

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;

Members

SSL_HELLO_REQUEST = 0u

Description

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

SSL_CERTIFICATE = 11u

ServerHello handshake message

ServerCertifiate handshake message

SSL_SERVER_HELLO_DONE = 14u

SSL_CLIENT_KEY_EXCHANGE = 16u

SSL_FINISHED = 20u

SSL_ALERT_HANDSHAKE_FAILURE =

40u+0x80

SSL_NO_MESSAGE = 0xff

ServerHelloDone handshake message

ClientKeyExchange handshake message

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)

HandshakeFailure alert message (dummy value used internally)

No message is currently requested (internally used value)

Description

Describes the types of SSL messages (handshake and alerts)

10.17.4.43

SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 Macro

File

SSL.c

#define

SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 0x0003u

Description

This is macro SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5.

10.17.4.44

SSL_RSA_WITH_ARCFOUR_128_MD5 Macro

File

SSL.c

502

10.17 SSL Microchip TCP/IP Stack Help

#define

SSL_RSA_WITH_ARCFOUR_128_MD5 0x0004u

Description

This is macro SSL_RSA_WITH_ARCFOUR_128_MD5.

SSL Internal Members

10.17.4.45

SSL_SESSION Structure

File

SSL.h

C typedef struct

{

BYTE sessionID[32];

BYTE masterSecret[48];

} SSL_SESSION;

Members

BYTE sessionID[32];

BYTE masterSecret[48];

Description

The SSL Session ID for this session

Associated Master Secret for this session

Description

Storage space for SSL Session identifiers. (The SessionID and MasterSecret)

10.17.4.46

SSL_SESSION_SIZE Macro

File

SSL.h

#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

10.17.4.47

SSL_SESSION_SPACE Macro

File

SSL.h

#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

503

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.48

SSL_SESSION_STUB Structure

File

SSL.h

C typedef struct

{

DWORD_VAL tag;

DWORD lastUsed;

} SSL_SESSION_STUB;

Members

DWORD_VAL tag;

DWORD lastUsed;

Description

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

Tick count when session was last used

Description

Stub value for an SSL_SESSION ( see page 503). 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.

10.17.4.49

SSL_SESSION_TYPE Enumeration

File

SSL.h

C typedef enum

{

SSL_CLIENT,

SSL_SERVER

} SSL_SESSION_TYPE;

Members

SSL_CLIENT

SSL_SERVER

Description

SSL Session Type Enumeration

Description

Local device is the SSL client

Local device is the SSL host

10.17.4.50

SSL_STUB Structure

File

SSL.h

C typedef struct

{

WORD wRxBytesRem;

WORD wRxHsBytesRem;

BYTE rxProtocol;

BYTE rxHSType;

504

10.17 SSL Microchip TCP/IP Stack Help

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;

Members

WORD wRxBytesRem;

WORD wRxHsBytesRem;

BYTE rxProtocol;

BYTE rxHSType;

BYTE idSession;

BYTE idRxHash;

DWORD_VAL dwTemp; 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;

BYTE requestedMessage;

Description

Bytes left to read in current record

Bytes left to read in current Handshake submessage

Protocol for message being read

Handshake message being received

ID for associated session

ID for MAC hash (TX needs no persistence)

Used for state machine in RxCertificate

We are the server

ClientHello has been sent/received

ServerHello has been sent/received

ServerCertificate has been sent/received

ServerHelloDone has been sent/received

ClientKeyExchange has been sent/received

Remote node has sent a ChangeCipherSpec message

Remote node has sent a Finished message

We have sent a ChangeCipherSpec message

We have sent a Finished message

We expect a MAC at end of message

TRUE if a new session, FALSE if resuming

Whether or not a CloseNotify has been sent/received

TRUE if the connection is closed

TRUE when RSA op is in progress

TRUE if the session keys have been generated

Currently requested message to send, or 0xff

Description

Memory holder for general information associated with an SSL connections.

SSL Internal Members

505

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.51

SSL_STUB_SIZE Macro

File

SSL.h

#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

10.17.4.52

SSL_STUB_SPACE Macro

File

SSL.h

#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

10.17.4.53

SSL_VERSION Macro

File

SSL.h

#define

SSL_VERSION (0x0300u)

// SSL version number

Description

SSL version number

10.17.4.54

SSL_VERSION_HI Macro

File

SSL.h

#define

SSL_VERSION_HI (0x03u)

// SSL version number (high byte)

Description

SSL version number (high byte)

10.17.4.55

SSL_VERSION_LO Macro

File

SSL.h

506

10.17 SSL Microchip TCP/IP Stack Help

#define

SSL_VERSION_LO (0x00u)

// SSL version number (low byte)

Description

SSL version number (low byte)

10.17.4.56

SSLBufferAlloc Function

File

SSL.c

C static void

SSLBufferAlloc(

BYTE * id

);

Side Effects

None

Returns

id - Allocated buffer ID, or SSL_INVALID_ID ( see page 472) if none available

Description

Allocates a buffer for use.

Remarks

None

Preconditions

None

Parameters

Description

Where to store the allocated ID

10.17.4.57

SSLBufferFree Function

File

SSL.c

C static void

SSLBufferFree(

BYTE * id

);

Side Effects

None

Description

Specified buffer is released

Remarks

None

Preconditions

None

SSL Internal Members

507

10.17 SSL

Parameters

Outputs

Microchip TCP/IP Stack Help

Description

the buffer ID to free

id - SSL_INVALID_ID ( see page 472)

10.17.4.58

sslBufferID Variable

File

SSL.c

BYTE sslBufferID;

Description

Which buffer is loaded

SSL Internal Members

10.17.4.59

SSLBufferSync Function

File

SSL.c

C static void

SSLBufferSync(

BYTE id

);

Side Effects

None

Returns

None

Description

Specified buffer is loaded to RAM. Only loads if necessary, and saves any current buffer before switching.

Remarks

None

Preconditions

None

Parameters

Description

the buffer ID to sync to RAM

10.17.4.60

SSLFinishPartialRecord Macro

File

SSL.h

#define

SSLFinishPartialRecord(a) TCPSSLPutRecordHeader(a, NULL, TRUE);

508

10.17 SSL

Description

This is macro SSLFinishPartialRecord.

Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.61

SSLFlushPartialRecord Macro

File

SSL.h

#define

SSLFlushPartialRecord(a) TCPSSLPutRecordHeader(a, NULL, FALSE);

Description

This is macro SSLFlushPartialRecord.

10.17.4.62

sslHash Variable

File

SSL.c

HASH_SUM sslHash;

Description

Hash storage

10.17.4.63

SSLHashAlloc Function

File

SSL.c

C static void

SSLHashAlloc(

BYTE * id

);

Side Effects

None

Description

Allocates a hash for use.

Remarks

None

Preconditions

None

Parameters

Outputs

Description

Where to store the allocated ID

id - Allocated hash ID, or SSL_INVALID_ID ( see page 472) if none available

509

10.17 SSL Microchip TCP/IP Stack Help

10.17.4.64

SSLHashFree Function

File

SSL.c

C static void

SSLHashFree(

BYTE * id

);

Side Effects

None

Description

Specified hash is released

Remarks

None

Preconditions

None

Parameters

Outputs

Description

the hash ID to free

id - SSL_INVALID_ID ( see page 472)

10.17.4.65

sslHashID Variable

File

SSL.c

BYTE sslHashID;

Description

Which hash is loaded

10.17.4.66

SSLHashSync Function

File

SSL.c

C static void

SSLHashSync(

BYTE id

);

Side Effects

None

Returns

None

SSL Internal Members

510

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

Description

Specified hash is loaded to RAM. Only loads if necessary, and saves any current hash before switching.

Remarks

None

Preconditions

None

Parameters

Description

the hash ID to sync to RAM

10.17.4.67

sslKeys Variable

File

SSL.c

SSL_KEYS sslKeys;

Description

The current SSL session

10.17.4.68

sslKeysID Variable

File

SSL.c

BYTE sslKeysID;

Description

Which SSL_KEYS ( see page 500) are loaded

10.17.4.69

SSLKeysSync Function

File

SSL.c

C static void

SSLKeysSync(

BYTE id

);

Side Effects

None

Returns

None

Description

Specified key set is loaded to RAM. Only loads if necessary, and saves any current key set before switching.

511

10.17 SSL

Remarks

None

Preconditions

None

Parameters

Microchip TCP/IP Stack Help

Description

the key set ID to sync to RAM

10.17.4.70

SSLMACAdd Function

File

SSL.h

C void

SSLMACAdd(

BYTE* data,

WORD len

);

Description

This is function SSLMACAdd.

10.17.4.71

SSLMACBegin Function

File

SSL.h

C void

SSLMACBegin(

BYTE* MACSecret,

DWORD seq,

BYTE protocol,

WORD len

);

Description

This is function SSLMACBegin.

10.17.4.72

SSLMACCalc Function

File

SSL.h

C void

SSLMACCalc(

BYTE* MACSecret,

BYTE* result

);

Description

This is function SSLMACCalc.

SSL Internal Members

512

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.73

SSLRSAOperation Function

File

SSL.c

C static

RSA_STATUS SSLRSAOperation();

Side Effects

None

Returns

None

Description

Pauses connection processing until RSA calculation is complete.

Remarks

This function exists outside of the handshaking functions so that the system does not incur the expense of resuming and suspending handshake hashes.

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 ( see page 523) to be synchronized.

Section

Function Prototypes

************************************************************************

Cryptographic Calculation Functions

10.17.4.74

sslRSAStubID Variable

File

SSL.c

BYTE sslRSAStubID;

Description

Which stub is using RSA, if any

10.17.4.75

SSLRxAlert Function

File

SSL.c

C static void

SSLRxAlert(

sslStub ( see page 523) is synchronized

);

513

10.17 SSL Microchip TCP/IP Stack Help

Side Effects

None

Returns

None

Description

Receives an alert message and decides what to do

Remarks

None

Preconditions

Parameters

hTCP

Description

the TCP Socket to read from

SSL Internal Members

10.17.4.76

SSLRxAntiqueClientHello Function

File

SSL.c

C static void

SSLRxAntiqueClientHello(

);

Side Effects

None

Returns

None

Description

Receives the SSLv2 ClientHello message, initiating a new SSL session with a client

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.

Preconditions

Handshake hasher is started, and SSL has a stub assigned.

Parameters

hTCP

Description

the TCP Socket to send the message to

10.17.4.77

SSLRxCCS Function

File

SSL.c

514

10.17 SSL Microchip TCP/IP Stack Help

C static void

SSLRxCCS(

sslStub ( see page 523) is synchronized.

);

Side Effects

None

Returns

None

Description

Receives a ChangeCipherSpec from the remote server

Remarks

None

Preconditions

Parameters

hTCP

Description

the TCP Socket to read from

10.17.4.78

SSLRxClientHello Function

File

SSL.c

C static void

SSLRxClientHello(

);

Side Effects

None

Returns

None

Description

Receives the ClientHello message, initiating a new SSL session with a client

Remarks

None

Preconditions

Handshake hasher is started, and SSL has a stub assigned.

Parameters

hTCP

Description

the TCP Socket to send the message to

SSL Internal Members

515

10.17 SSL Microchip TCP/IP Stack Help

10.17.4.79

SSLRxClientKeyExchange Function

File

SSL.c

C static void

SSLRxClientKeyExchange(

sslStub ( see page 523) is synchronized and HSStart ( see page 493)() has been called.

);

Side Effects

None

Returns

None

Description

Receives the ClientKeyExchange message and begins the decryption process.

Remarks

None

Preconditions

Parameters

hTCP

Description

the TCP Socket to read from

10.17.4.80

SSLRxFinished Function

File

SSL.c

C static void

SSLRxFinished(

sslStub ( see page 523) is synchronized and HSStart ( see page 493)() has been called.

);

Side Effects

None

Returns

None

Description

Receives the Finished message from remote node

Remarks

None

Preconditions

SSL Internal Members

516

10.17 SSL

Parameters

hTCP

Microchip TCP/IP Stack Help

Description

the TCP Socket to read from

SSL Internal Members

10.17.4.81

SSLRxHandshake Function

File

SSL.h

C void

SSLRxHandshake(

);

Returns

None

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

hTCP

Description

The TCP socket to read a handshake message from

10.17.4.82

SSLRxRecord Function

File

SSL.h

WORD SSLRxRecord(

BYTE sslStubID

);

Returns

WORD indicating the number of data bytes there were decrypted but left in the stream.

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.

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.

Preconditions

The specified SSL stub is initialized and the TCP socket is connected.

517

10.17 SSL

Parameters

hTCP id

Microchip TCP/IP Stack Help

Description

The TCP socket from which to read

The active SSL stub ID

SSL Internal Members

10.17.4.83

SSLRxServerCertificate Function

File

SSL.c

C static void

SSLRxServerCertificate(

sslStub ( see page 523) is synchronized and HSStart ( see page 493)() has been called.

);

Side Effects

None

Returns

None

Description

Receives ServerCertificate from the remote server, locates the public key information, and executes RSA operation.

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.

Preconditions

Parameters

hTCP

Description

the TCP Socket to read from

10.17.4.84

SSLRxServerHello Function

File

SSL.c

C static void

SSLRxServerHello(

sslStub ( see page 523) is synchronized and HSStart ( see page 493)() has been called.

);

Side Effects

None

Returns

None

Description

Receives the ServerHello from the remote server

518

10.17 SSL Microchip TCP/IP Stack Help

Remarks

None

Preconditions

Parameters

hTCP

Description

the TCP Socket to read from

10.17.4.85

sslSession Variable

File

SSL.c

SSL_SESSION sslSession;

Description

Current session data

10.17.4.86

sslSessionID Variable

File

SSL.c

BYTE sslSessionID;

Description

Which session is loaded

10.17.4.87

SSLSessionMatchID Function

File

SSL.c

C static

BYTE SSLSessionMatchID(

BYTE* SessionID

);

Side Effects

None

Returns

The matched session ID, or SSL_INVALID_ID ( see page 472) if not found

Description

Locates a cached SSL session for reuse. Syncs found session into RAM.

Remarks

None

SSL Internal Members

519

10.17 SSL

Preconditions

None

Parameters

SessionID

Section

Server messages

Microchip TCP/IP Stack Help

Description

the session identifier to match

10.17.4.88

SSLSessionMatchIP Function

File

SSL.c

C static

BYTE SSLSessionMatchIP(

IP_ADDR ip

);

Side Effects

None

Returns

The matched session ID, or SSL_INVALID_ID ( see page 472) if not found

Description

Locates a cached SSL session for reuse

Remarks

None

Preconditions

None

Parameters

Section

Client messages

Description

the host session to match

10.17.4.89

SSLSessionNew Function

File

SSL.c

C static

BYTE SSLSessionNew();

Side Effects

None

Returns

Allocated Session ID, or SSL_INVALID_ID ( see page 472) if none available

SSL Internal Members

520

10.17 SSL

Description

Finds space for a new SSL session

Remarks

None

Preconditions

None

Microchip TCP/IP Stack Help

10.17.4.90

sslSessionStubs Variable

File

SSL.c

SSL_SESSION_STUB sslSessionStubs[MAX_SSL_SESSIONS];

Description

8 byte session stubs

SSL Internal Members

10.17.4.91

SSLSessionSync Function

File

SSL.c

C static void

SSLSessionSync(

BYTE id

);

Side Effects

None

Returns

None

Description

Specified session is loaded to RAM. Only loads if necessary, and saves any current session before switching if it has been updated.

Remarks

None

Preconditions

None

Parameters

Description

the session ID to sync to RAM

521

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

10.17.4.92

SSLSessionUpdated Macro

File

SSL.c

#define

SSLSessionUpdated sslSessionUpdated = TRUE;

Description

This is macro SSLSessionUpdated.

10.17.4.93

sslSessionUpdated Variable

File

SSL.c

BOOL sslSessionUpdated;

Description

Whether or not it has been updated

10.17.4.94

SSLStartPartialRecord Function

File

SSL.h

C void

SSLStartPartialRecord(

SSLFlushPartialRecord ( see page 509) and SSLFinishPartialRecord ( see page 508) must be called to write remaining

BYTE sslStubID,

BYTE txProtocol,

WORD wLen

);

Returns

None

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,

data, finalize, and prepare for a new record.

Remarks

Partial messages do not support the current cipher spec, so this can only be used during the handshake procedure.

Preconditions

The specified SSL stub is initialized and the TCP socket is connected.

Parameters

hTCP id

Description

The TCP socket with data waiting to be transmitted

The active SSL stub ID

522

10.17 SSL txPortocol wLen

Microchip TCP/IP Stack Help

The SSL protocol number to attach to this record

The length of all the data to be sent

10.17.4.95

sslStub Variable

File

SSL.c

SSL_STUB sslStub;

Description

The current SSL stub

10.17.4.96

SSLStubAlloc Function

File

SSL.c

C static

BOOL SSLStubAlloc();

Side Effects

None

Returns

TRUE if stub was allocated, FALSE otherwise

Description

Allocates a stub for use.

Remarks

None

Preconditions

None

Parameters

Outputs

Description

None

10.17.4.97

SSLStubFree Function

File

SSL.c

C static void

SSLStubFree(

BYTE id

);

Side Effects

None

SSL Internal Members

523

10.17 SSL

Returns

None

Description

Specified stub is released

Remarks

None

Preconditions

None

Parameters

Outputs

Microchip TCP/IP Stack Help

Description

the stub ID to free

None

10.17.4.98

sslStubID Variable

File

SSL.c

BYTE sslStubID;

Description

Which SSL_STUB ( see page 504) is loaded

10.17.4.99

SSLStubSync Function

File

SSL.c

C static void

SSLStubSync(

BYTE id

);

Side Effects

None

Returns

None

Description

Specified stub is loaded to RAM. Only loads if necessary, and saves any current stub before switching.

Remarks

None

Preconditions

None

SSL Internal Members

524

10.17 SSL

Parameters

Section

Ethernet Buffer RAM Management

Microchip TCP/IP Stack Help

Description

the stub ID to sync to RAM

SSL Internal Members

10.17.4.100

SSLTerminate Function

File

SSL.h

C void

SSLTerminate(

BYTE sslStubId

);

Returns

None

Description

Terminates an SSL connection and releases allocated resources.

Preconditions

None

Parameters

Description

the SSL stub ID to terminate

10.17.4.101

SSLTxCCSFin Function

File

SSL.c

C static void

SSLTxCCSFin(

sslStub ( see page 523) is synchronized, and the current session has a valid pre-master secret to use.

);

Side Effects

None

Returns

None

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.

Remarks

None

Preconditions

525

10.17 SSL

Parameters

hTCP

Section

Client and server messages

Microchip TCP/IP Stack Help

Description

the TCP Socket to write the message to

SSL Internal Members

10.17.4.102

SSLTxClientHello Function

File

SSL.c

C static void

SSLTxClientHello(

);

Side Effects

None

Returns

None

Description

Transmits the ClientHello message to initiate a new SSL session with the server.

Remarks

None

Preconditions

Enough space is available in hTCP to write the entire message.

Parameters

hTCP

Description

the TCP Socket to send the message to

10.17.4.103

SSLTxClientKeyExchange Function

File

SSL.c

C static void

SSLTxClientKeyExchange(

sslStub ( see page 523) is synchronized, sslStub.dwTemp.v[1] contains the length of the public key, and the RxBuffer

);

Side Effects

None

Returns

None

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.

526

10.17 SSL Microchip TCP/IP Stack Help SSL Internal Members

Remarks

None

Preconditions

contains the encrypted pre-master secret at address 0x80.

Parameters

hTCP

Description

the TCP Socket to write the message to

10.17.4.104

SSLTxMessage Function

File

SSL.h

C void

SSLTxMessage(

SSL_MESSAGES ( see page 501).

BYTE sslStubID,

BYTE msg

);

Returns

None

Description

This function transmits a specific SSL message for handshakes and alert messages. Supported messages are listed in

Preconditions

The specified SSL stub is initialized and the TCP socket is connected.

Parameters

hTCP id msg

Description

The TCP socket with data waiting to be transmitted

The active SSL stub ID

One of the SSL_MESSAGES ( see page 501) types to send

10.17.4.105

SSLTxRecord Function

File

SSL.h

C void

SSLTxRecord(

BYTE sslStubID,

BYTE txProtocol

);

Returns

None

Description

Transmits all pending data in the TCP TX buffer as an SSL record using the specified protocol. This function transparently

527

10.17 SSL Microchip TCP/IP Stack Help 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

hTCP id txPortocol

Description

The TCP socket with data waiting to be transmitted

The active SSL stub ID

The SSL protocol number to attach to this record

SSL Internal Members

10.17.4.106

SSLTxServerCertificate Function

File

SSL.c

C static void

SSLTxServerCertificate(

);

Side Effects

None

Returns

None

Description

Transmits the Certificate message with the server's specified public key certificate.

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

Preconditions

None

Parameters

hTCP

Description

the TCP Socket to send the message to

10.17.4.107

SSLTxServerHello Function

File

SSL.c

C static void

SSLTxServerHello(

);

Side Effects

None

528

10.17 SSL

Returns

None

Description

Transmits the ServerHello message.

Remarks

None

Preconditions

None

Parameters

hTCP

Microchip TCP/IP Stack Help

Description

the TCP Socket to send the message to

10.17.4.108

SSLTxServerHelloDone Function

File

SSL.c

C static void

SSLTxServerHelloDone(

);

Side Effects

None

Returns

None

Description

Transmits the ServerHelloDone message.

Remarks

None

Preconditions

None

Parameters

hTCP

Description

the TCP Socket to send the message to

10.17.5

Files

Files

Name

Module

SSL_RSA_CLIENT_SIZE ( see page 476)

Description

This is file SSLClientSize.h.

Files

529

10.18 TCP Microchip TCP/IP Stack Help

10.17.5.1

SSLClientSize.h

Macros

Name

Description

Size of Encryption Buffer (must be larger than key size)

Description

This is file SSLClientSize.h.

10.18

TCP

Functions

Name

WFGetTCBSize ( see page

576)

Description

This is function WFGetTCBSize.

Variables

Name

NextPort ( see page 577)

Description

Tracking variable for next local client port number

Description

TCP is a standard transport layer protocol described in RFC 793. It provides reliable stream-based connections over unreliable networks, and forms the foundation for HTTP, SMTP, and many other protocol standards.

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:

530

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

Sockets ( see page 157) are opened using TCPOpen ( see page 547). 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 ( see page 545) will be sufficient, but TCPWasReset ( see page 553) may also be used for listening sockets that may turn over quickly.

To write data, call TCPIsPutReady ( see page 546) to check how much space is available. Then, call any of the TCPPut (

see page 549) family of functions to write data as space is available. Once complete, call TCPFlush ( see page 542) 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 ( see page 546) to determine how many bytes are ready to be retrieved. Then use the

TCPGet ( see page 542) family of functions to read data from the socket, and/or the TCPFind ( see page 538) 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 ( see page 538), 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 ( see page 102) or GenericTCPServer ( see page 105) examples, or

read the associated RFC.

10.18.1

TCP Public Members

Functions

Name

TCPAdjustFIFOSize ( see page 536)

Description

Adjusts the relative sizes of the RX and TX buffers.

TCPClose ( see page 537)

Disconnects an open socket and destroys the socket handle, including server mode socket handles.

TCPDiscard ( see page 537) Discards any pending data in the TCP RX FIFO.

TCPDisconnect ( see page

538)

Disconnects an open socket.

TCPFindArrayEx ( see page 539)

Searches for a string in the TCP RX buffer.

TCPFindEx ( see page 540) Searches for a byte in the TCP RX buffer.

531

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

TCPFindROMArrayEx ( see page 541)

Searches for a ROM string in the TCP RX buffer.

TCPFlush ( see page 542)

Immediately transmits all pending TX data.

TCPGet ( see page 542)

TCPGetArray ( see page

543)

TCPGetRemoteInfo ( see page 543)

Retrieves a single byte to a TCP socket.

Reads an array of data bytes from a TCP socket's receive FIFO. The data is removed from the FIFO in the process.

Obtains information about a currently open socket.

TCPGetRxFIFOFree ( see page 544)

TCPGetTxFIFOFull ( see page 545)

TCPIsConnected ( see page 545)

Determines how many bytes are free in the RX FIFO.

Determines how many bytes are pending in the TCP TX FIFO.

Determines if a socket has an established connection.

TCPIsGetReady ( see page

546)

TCPIsPutReady ( see page

546)

Determines how many bytes can be read from the TCP RX buffer.

Determines how much free space is available in the TCP TX buffer.

TCPOpen ( see page 547)

Opens a TCP socket for listening or as a client.

TCPPeek ( see page 548)

Peaks at one byte in the TCP RX FIFO without removing it from the buffer.

Reads a specified number of data bytes from the TCP RX FIFO without removing them from the buffer.

Writes a single byte to a TCP socket.

Writes an array from RAM to a TCP socket.

TCPPeekArray ( see page

549)

TCPPut ( see page 549)

TCPPutArray ( see page

550)

TCPPutROMArray ( see page 550)

TCPPutROMString ( see page 551)

TCPPutString ( see page

552)

TCPRAMCopy ( see page

552)

TCPRAMCopyROM ( see page 553)

TCPWasReset ( see page

553)

Writes an array from ROM to a TCP socket.

Writes a null-terminated string from ROM to a TCP socket. The null-terminator is not copied to the socket.

Writes a null-terminated string from RAM to a TCP socket. The null-terminator is not copied to the socket.

Copies data to/from various memory mediums.

Self-clearing semaphore inidicating socket reset.

Macros

Name Description

INVALID_SOCKET ( see page 533) The socket is invalid or could not be opened

UNKNOWN_SOCKET ( see page

533)

The socket is not known

TCP_ADJUST_GIVE_REST_TO_RX

( see page 534)

Resize flag: extra bytes go to RX

TCP_ADJUST_GIVE_REST_TO_TX

( see page 534)

Resize flag: extra bytes go to TX

Resize flag: attempt to preserve RX buffer

TCP_ADJUST_PRESERVE_RX ( see page 534)

TCP_ADJUST_PRESERVE_TX ( see page 534)

TCP_OPEN_IP_ADDRESS ( see page 534)

Resize flag: attempt to preserve TX buffer

Emit an undeclared identifier diagnostic if code tries to use

TCP_OPEN_IP_ADDRESS while STACK_CLIENT_MODE feature is not enabled.

532

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

TCP_OPEN_NODE_INFO ( see page 535)

TCP_OPEN_RAM_HOST ( see page 535)

TCP_OPEN_ROM_HOST ( see page 535)

Emit an undeclared identifier diagnostic if code tries to use

TCP_OPEN_NODE_INFO while STACK_CLIENT_MODE feature is not enabled.

Emit an undeclared identifier diagnostic if code tries to use

TCP_OPEN_RAM_HOST while STACK_CLIENT_MODE feature is not enabled.

Emit an undeclared identifier diagnostic if code tries to use

TCP_OPEN_ROM_HOST while STACK_CLIENT_MODE feature is not enabled.

Create a server socket and ignore dwRemoteHost.

TCP_OPEN_SERVER ( see page

535)

TCPConnect ( see page 537)

TCPFind ( see page 538)

TCPFindArray ( see page 539)

Alias to TCPOpen ( see page 547) as a client.

Alias to TCPFindEx ( see page 540) with no length parameter.

Alias to TCPFindArrayEx ( see page 539) with no length parameter.

TCPFindROMArray ( see page 541) Alias to TCPFindROMArrayEx ( see page 541) with no length

parameter.

TCPGetRxFIFOFull ( see page 544) Alias to TCPIsGetReady ( see page 546) provided for API

completeness

TCPGetTxFIFOFree ( see page

544)

TCPListen ( see page 546)

Alias to TCPIsPutReady ( see page 546) provided for API

completeness

Alias to TCPOpen ( see page 547) as a server.

Module

Description

The following functions and variables are available to the stack application.

10.18.1.1

INVALID_SOCKET Macro

File

TCP.h

#define

INVALID_SOCKET (0xFE)

// The socket is invalid or could not be opened

Description

The socket is invalid or could not be opened

10.18.1.2

UNKNOWN_SOCKET Macro

File

TCP.h

#define

UNKNOWN_SOCKET (0xFF)

// The socket is not known

Description

The socket is not known

533

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

10.18.1.3

TCP_ADJUST_GIVE_REST_TO_RX Macro

File

TCP.h

#define

TCP_ADJUST_GIVE_REST_TO_RX 0x01u

// Resize flag: extra bytes go to RX

Description

Resize flag: extra bytes go to RX

10.18.1.4

TCP_ADJUST_GIVE_REST_TO_TX Macro

File

TCP.h

#define

TCP_ADJUST_GIVE_REST_TO_TX 0x02u

// Resize flag: extra bytes go to TX

Description

Resize flag: extra bytes go to TX

10.18.1.5

TCP_ADJUST_PRESERVE_RX Macro

File

TCP.h

#define

TCP_ADJUST_PRESERVE_RX 0x04u

// Resize flag: attempt to preserve RX buffer

Description

Resize flag: attempt to preserve RX buffer

10.18.1.6

TCP_ADJUST_PRESERVE_TX Macro

File

TCP.h

#define

TCP_ADJUST_PRESERVE_TX 0x08u

// Resize flag: attempt to preserve TX buffer

Description

Resize flag: attempt to preserve TX buffer

10.18.1.7

TCP_OPEN_IP_ADDRESS Macro

File

TCP.h

534

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

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

10.18.1.8

TCP_OPEN_NODE_INFO Macro

File

TCP.h

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

10.18.1.9

TCP_OPEN_RAM_HOST Macro

File

TCP.h

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

10.18.1.10

TCP_OPEN_ROM_HOST Macro

File

TCP.h

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

10.18.1.11

TCP_OPEN_SERVER Macro

File

TCP.h

#define

TCP_OPEN_SERVER 0u

535

10.18 TCP Microchip TCP/IP Stack Help

Description

Create a server socket and ignore dwRemoteHost.

TCP Public Members

10.18.1.12

TCPAdjustFIFOSize Function

File

TCP.h

BOOL TCPAdjustFIFOSize(

If neither or both of TCP_ADJUST_GIVE_REST_TO_TX ( see page 534) and TCP_ADJUST_GIVE_REST_TO_RX ( see page 534) are set, the function distributes the remaining space equally.

WORD wMinRXSize,

WORD wMinTXSize,

BYTE vFlags

);

Side Effects

Any unacknowledged or untransmitted data in the TX FIFO is always deleted.

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.

Received data can be preserved as long as the buffer is expanding and has not wrapped.

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.

Preconditions

TCP is initialized.

Parameters

hTCP wMinRXSize wMinTXSize vFlags

Description

The socket to be adjusted

Minimum number of byte for the RX FIFO

Minimum number of bytes for the RX FIFO

Any combination of TCP_ADJUST_GIVE_REST_TO_RX ( see page 534),

TCP_ADJUST_GIVE_REST_TO_TX ( see page 534),

TCP_ADJUST_PRESERVE_RX ( see page 534).

TCP_ADJUST_PRESERVE_TX ( see page 534) is not currently supported.

Return Values

TRUE

FALSE

Description

The FIFOs were adjusted successfully

Minimum RX, Minimum TX, or flags couldn't be accommodated and therefore the socket was left unchanged.

536

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

10.18.1.13

TCPConnect Macro

File

TCP.h

#define

TCPConnect(remote,port) TCPOpen((DWORD)remote, TCP_OPEN_NODE_INFO, port,

TCP_PURPOSE_DEFAULT)

Description

This function is an alias to TCPOpen ( see page 547) for client sockets. It is provided for backwards compatibility with older versions of the stack. New applications should use the TCPOpen ( see page 547) API instead.

10.18.1.14

TCPClose Function

File

TCP.h

C void

TCPClose(

identically to the TCPDisconnect ( see page 538)() function, except that both client and server mode socket handles are

);

Returns

None

Description

Disconnects an open socket and destroys the socket handle, including server mode socket handles. This function performs

relinquished to the TCP/IP stack upon return.

Preconditions

None

Parameters

hTCP

Description

Handle to the socket to disconnect and close.

10.18.1.15

TCPDiscard Function

File

TCP.h

C void

TCPDiscard(

);

Returns

None

Description

Discards any pending data in the TCP RX FIFO.

537

10.18 TCP

Preconditions

TCP is initialized.

Parameters

hTCP

Microchip TCP/IP Stack Help TCP Public Members

Description

The socket whose RX FIFO is to be cleared.

10.18.1.16

TCPDisconnect Function

File

TCP.h

C void

TCPDisconnect(

the TCP/IP stack, call the TCPClose ( see page 537)() API instead of TCPDisconnect().

);

Returns

None

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

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.

Preconditions

None

Parameters

hTCP

Description

Handle of the socket to disconnect.

10.18.1.17

TCPFind Macro

File

TCP.h

#define

TCPFind(a,b,c,d) TCPFindEx(a,b,c,0,d)

538

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

Description

This function is an alias to TCPFindEx ( see page 540) with no length parameter. It is provided for backwards compatibility

with an older API.

10.18.1.18

TCPFindArray Macro

File

TCP.h

#define

TCPFindArray(a,b,c,d,e) TCPFindArrayEx(a,b,c,d,0,e)

Description

This function is an alias to TCPFindArrayEx ( see page 539) with no length parameter. It is provided for backwards

compatibility with an older API.

10.18.1.19

TCPFindArrayEx Function

File

TCP.h

WORD TCPFindArrayEx(

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.

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.

Preconditions

TCP is initialized.

Parameters

hTCP cFindArray wLen wStart

Description

The socket to search within.

The array of bytes to find in the buffer.

Length of cFindArray.

Zero-indexed starting position within the buffer.

539

10.18 TCP wSearchLen bTextCompare

Return Values

0xFFFF

Otherwise

Microchip TCP/IP Stack Help TCP Public Members

Length from wStart to search in the buffer.

TRUE for case-insensitive text search, FALSE for binary search

Description

Search array not found

Zero-indexed position of the first occurrance

10.18.1.20

TCPFindEx Function

File

TCP.h

WORD TCPFindEx(

TCPFindROMArray(a,b,c,d,e) TCPFindArray(a,(BYTE*)b,c,d,e)

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.

Remarks

RAM for final comparison. This has proven to be significantly faster than searching for full header name strings outright.

Preconditions

TCP is initialized.

Parameters

hTCP cFind wStart wSearchLen bTextCompare

Return Values

0xFFFF

Otherwise

Description

The socket to search within.

The byte to find in the buffer.

Zero-indexed starting position within the buffer.

Length from wStart to search in the buffer.

TRUE for case-insensitive text search, FALSE for binary search

Description

Search array not found

Zero-indexed position of the first occurrance

540

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

10.18.1.21

TCPFindROMArray Macro

File

TCP.h

#define

Description

This function is an alias to TCPFindROMArrayEx ( see page 541) with no length parameter. It is provided for backwards

compatibility with an older API.

10.18.1.22

TCPFindROMArrayEx Function

File

TCP.h

WORD TCPFindROMArrayEx(

This function is aliased to TCPFindArrayEx ( see page 539) on non-PIC18 platforms.

ROM BYTE* cFindArray,

WORD wLen,

WORD wStart,

WORD wSearchLen,

BOOL bTextCompare

);

Description

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.

Remarks

RAM for final comparison. This has proven to be significantly faster than searching for full header name strings outright.

Preconditions

TCP is initialized.

Parameters

hTCP cFindArray wLen wStart wSearchLen bTextCompare

Description

The socket to search within.

The array of bytes to find in the buffer.

Length of cFindArray.

Zero-indexed starting position within the buffer.

Length from wStart to search in the buffer.

TRUE for case-insensitive text search, FALSE for binary search

541

10.18 TCP

Return Values

0xFFFF

Otherwise

Microchip TCP/IP Stack Help

Description

Search array not found

Zero-indexed position of the first occurrance

TCP Public Members

10.18.1.23

TCPFlush Function

File

TCP.h

C void

TCPFlush(

be sent when either a) the TX buffer is half full or b) the TCP_AUTO_TRANSMIT_TIMEOUT_VAL ( see page 570) (default:

);

Returns

None

Description

This function immediately transmits all pending TX data with a PSH flag. If this function is not called, data will automatically

40ms) has elapsed.

Remarks

SSL application data is automatically flushed, so this function has no effect for SSL sockets.

Preconditions

TCP is initialized and the socket is connected.

Parameters

hTCP

Description

The socket whose data is to be transmitted.

10.18.1.24

TCPGet Function

File

TCP.h

BOOL TCPGet(

BYTE* byte

);

Description

Retrieves a single byte to a TCP socket.

Preconditions

TCP is initialized.

Parameters

hTCP byte

Description

The socket from which to read.

Pointer to location in which the read byte should be stored.

542

10.18 TCP

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help

Description

A byte was read from the buffer.

The buffer was empty, or the socket is not connected.

TCP Public Members

10.18.1.25

TCPGetArray Function

File

TCP.h

WORD TCPGetArray(

SOCKET_INFO* TCPGetRemoteInfo(

BYTE* buffer,

WORD count

);

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.

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

hTCP buffer len

Description

The socket from which data is to be read.

Pointer to the array to store data that was read.

Number of bytes to be read.

10.18.1.26

TCPGetRemoteInfo Function

File

TCP.h

The SOCKET_INFO ( see page 555) structure associated with this socket. This structure is allocated statically by the

);

Returns

function and is valid only until the next time TCPGetRemoteInfo() is called.

Description

Returns the SOCKET_INFO ( see page 555) 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.

543

10.18 TCP

Parameters

hTCP

Microchip TCP/IP Stack Help

Description

The socket to check.

TCP Public Members

10.18.1.27

TCPGetRxFIFOFree Function

File

TCP.h

WORD TCPGetRxFIFOFree(

some data using one of the TCPGet ( see page 542) family functions.

);

Returns

The number of bytes free in the TCP RX FIFO. If zero, no additional data can be received until the application removes

Description

Determines how many bytes are free in the RX FIFO.

Preconditions

TCP is initialized.

Parameters

hTCP

Description

The socket to check.

10.18.1.28

TCPGetRxFIFOFull Macro

File

TCP.h

#define

TCPGetRxFIFOFull(a) TCPIsGetReady(a)

Description

Alias to TCPIsGetReady ( see page 546) provided for API completeness

10.18.1.29

TCPGetTxFIFOFree Macro

File

TCP.h

#define

TCPGetTxFIFOFree(a) TCPIsPutReady(a)

Description

Alias to TCPIsPutReady ( see page 546) provided for API completeness

544

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

10.18.1.30

TCPGetTxFIFOFull Function

File

TCP.h

WORD TCPGetTxFIFOFull(

);

Returns

Number of bytes pending to be flushed in the TCP TX FIFO.

Description

Determines how many bytes are pending in the TCP TX FIFO.

Preconditions

TCP is initialized.

Parameters

hTCP

Description

The socket to check.

10.18.1.31

TCPIsConnected Function

File

TCP.h

BOOL TCPIsConnected(

TCPOpen ( see page 547) to determine when the connection is set up and ready for use. This function was historically

);

Description

This function determines if a socket has an established connection to a remote node. Call this function after calling

used to check for disconnections, but TCPWasReset ( see page 553) is now a more appropriate solution.

Remarks

A socket is said to be connected only if it is in the TCP_ESTABLISHED state. Sockets ( see page 157) in the process of

opening or closing will return FALSE.

Preconditions

TCP is initialized.

Parameters

hTCP

Return Values

TRUE

FALSE

Description

The socket to check.

Description

The socket has an established connection to a remote node.

The socket is not currently connected.

545

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

10.18.1.32

TCPIsGetReady Function

File

TCP.h

WORD TCPIsGetReady(

);

Returns

The number of bytes available to be read from the TCP RX buffer.

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

hTCP

Description

The socket to check.

10.18.1.33

TCPIsPutReady Function

File

TCP.h

WORD TCPIsPutReady(

TCPListen(port) TCPOpen(0, TCP_OPEN_SERVER, port, TCP_PURPOSE_DEFAULT)

);

Returns

The number of bytes available to be written in the TCP TX buffer.

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

hTCP

Description

The socket to check.

10.18.1.34

TCPListen Macro

File

TCP.h

546

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

#define

Description

This function is an alias to TCPOpen ( see page 547) for server sockets. It is provided for backwards compatibility with older versions of the stack. New applications should use the TCPOpen ( see page 547) API instead.

10.18.1.35

TCPOpen Function

File

TCP.h

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 ( see page 174) 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 ( see page 180) 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 ( see page 157) are statically allocated on boot, but can be claimed with this function and freed using

TCPDisconnect ( see page 538) or TCPClose ( see page 537) (for client sockets). Server sockets can be freed using

TCPClose ( see page 537) only (calls to TCPDisconnect ( see page 538) will return server sockets to the listening state,

allowing reuse).

Remarks

This function replaces the old TCPConnect ( see page 537) and TCPListen ( see page 546) functions.

If TCP_OPEN_RAM_HOST ( see page 535) or TCP_OPEN_ROM_HOST ( see page 535) are used for the destination

type, the DNS client module must also be enabled (STACK_USE_DNS must be defined in TCPIPConfig.h).

Preconditions

TCP is initialized.

Example

// 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

547

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

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

Parameters

dwRemoteHost vRemoteHostType wPort

Description

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 ( see page 545) returns TRUE.

This parameter is ignored for server sockets.

Any one of the following flags to identify the meaning of the dwRemoteHost parameter:

• TCP_OPEN_SERVER ( see page 535) - Open a server socket and

ignore the dwRemoteHost parameter.

• TCP_OPEN_RAM_HOST ( see page 535) - Open a client socket and

connect ( see page 176) 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 ( see page 535) - Open a client socket and

connect ( see page 176) 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 ( see page 534) - Open a client socket and

connect ( see page 176) 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 ( see page 535) - Open a client socket and

connect ( see page 176) 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 ( see page 537)() 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.

TCP port to listen ( see page 180) on or connect ( see page 176) 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 ( see page 180) for

connections.

vSocketPurpose Any of the TCP_PURPOSE_* constants defined in TCPIPConfig.h or the

TCPIPConfig utility (see TCPSocketInitializer[] array).

Return Values

INVALID_SOCKET ( see page 533)

Otherwise

Description

No sockets of the specified type were available to be opened.

A TCP_SOCKET ( see page 558) handle. Save this handle and use it when

calling all other TCP APIs.

10.18.1.36

TCPPeek Function

File

TCP.h

548

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

BYTE TCPPeek(

Use the TCPPeekArray ( see page 549)() function to read more than one byte. It will perform better than calling TCPPeek()

WORD wStart

);

Description

Peaks at one byte in the TCP RX FIFO without removing it from the buffer.

Remarks

in a loop.

Preconditions

TCP is initialized.

Parameters

hTCP wStart

Description

The socket to peak from (read without removing from stream).

Zero-indexed starting position within the FIFO to peek from.

10.18.1.37

TCPPeekArray Function

File

TCP.h

WORD TCPPeekArray(

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

Remarks

None

Preconditions

TCP is initialized.

Parameters

hTCP vBuffer wLen wStart

Description

The socket to peak from (read without removing from stream).

Destination to write the peeked data bytes.

Length of bytes to peak from the RX FIFO and copy to vBuffer.

Zero-indexed starting position within the FIFO to start peeking from.

10.18.1.38

TCPPut Function

File

TCP.h

549

10.18 TCP

BOOL TCPPut(

BYTE byte

);

Description

Writes a single byte to a TCP socket.

Preconditions

TCP is initialized.

Parameters

hTCP byte

Return Values

TRUE

FALSE

Microchip TCP/IP Stack Help

Description

The socket to which data is to be written.

The byte to write.

TCP Public Members

Description

The byte was written to the transmit buffer.

The transmit buffer was full, or the socket is not connected.

10.18.1.39

TCPPutArray Function

File

TCP.h

WORD TCPPutArray(

BYTE* Data,

WORD Len

);

Returns

The number of bytes written to the socket. If less than len, the buffer became full or the socket is not conected.

Description

Writes an array from RAM to a TCP socket.

Preconditions

TCP is initialized.

Parameters

hTCP data len

Description

The socket to which data is to be written.

Pointer to the array to be written.

Number of bytes to be written.

10.18.1.40

TCPPutROMArray Function

File

TCP.h

550

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

WORD TCPPutROMArray(

This function is aliased to TCPPutArray ( see page 550) on non-PIC18 platforms.

ROM BYTE* Data,

WORD Len

);

Returns

The number of bytes written to the socket. If less than len, the buffer became full or the socket is not conected.

Description

Writes an array from ROM to a TCP socket.

Remarks

Preconditions

TCP is initialized.

Parameters

hTCP data len

Description

The socket to which data is to be written.

Pointer to the array to be written.

Number of bytes to be written.

10.18.1.41

TCPPutROMString Function

File

TCP.h

ROM BYTE* TCPPutROMString(

The return value of this function differs from that of TCPPutArray ( see page 550). To write long strings in a single state,

ROM BYTE* Data

);

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.

Description

Writes a null-terminated string from ROM to a TCP socket. The null-terminator is not copied to the socket.

Remarks

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 ( see page 552) on non-PIC18 platforms.

Preconditions

TCP is initialized.

Parameters

hTCP data

Description

The socket to which data is to be written.

Pointer to the string to be written.

551

10.18 TCP Microchip TCP/IP Stack Help TCP Public Members

10.18.1.42

TCPPutString Function

File

TCP.h

BYTE* TCPPutString(

The return value of this function differs from that of TCPPutArray ( see page 550). To write long strings in a single state,

BYTE* Data

);

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.

Description

Writes a null-terminated string from RAM to a TCP socket. The null-terminator is not copied to the socket.

Remarks

Preconditions

TCP is initialized.

Parameters

hTCP data

Description

The socket to which data is to be written.

Pointer to the string to be written.

10.18.1.43

TCPRAMCopy Function

File

TCP.c

C static void

TCPRAMCopy(

PTR_BASE wDest,

BYTE vDestType,

PTR_BASE wSource,

BYTE vSourceType,

WORD wLength

);

Returns

None

Description

This function copies data between memory mediums (PIC RAM, SPI RAM, and Ethernet buffer RAM).

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.

552

10.18 TCP

Preconditions

TCP is initialized.

Parameters

ptrDest vDestType ptrSource vSourceType wLength

Section

Function Prototypes

Microchip TCP/IP Stack Help TCP Public Members

Description

Address ( see page 152) to write to

Destination meidum (TCP_PIC_RAM, TCP_ETH_RAM, TCP_SPI_RAM)

Address ( see page 152) to copy from

Source medium (TCP_PIC_RAM, TCP_ETH_RAM, or TCP_SPI_RAM)

Number of bytes to copy

10.18.1.44

TCPRAMCopyROM Function

File

TCP.c

C static void

TCPRAMCopyROM(

PTR_BASE wDest,

BYTE wDestType,

ROM BYTE* wSource,

WORD wLength

);

Returns

None

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.

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 ( see page 552) on non-PIC18 platforms.

Preconditions

TCP is initialized.

Parameters

wDest wDestType wSource wLength

Description

Address ( see page 152) to write to

Destination meidum (TCP_PIC_RAM, TCP_ETH_RAM, TCP_SPI_RAM)

Address ( see page 152) to copy from

Number of bytes to copy

10.18.1.45

TCPWasReset Function

File

TCP.h

553

10.18 TCP Microchip TCP/IP Stack Help TCP Stack Members

BOOL TCPWasReset(

This function works for all possible disconnections: a call to TCPDisconnect ( see page 538), a FIN from the remote node,

);

Description

This function is a self-clearing semaphore indicating whether or not a socket has been disconnected since the previous call.

or an acknowledgement timeout caused by the loss of a network link. It also returns TRUE after the first call to TCPInit ( see page 559). 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 ( see page 545) 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 ( see page 545) 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

hTCP

Return Values

TRUE

FALSE

Description

The socket to check.

Description

The socket has been disconnected since the previous call.

The socket has not been disconnected since the previous call.

10.18.2

TCP Stack Members

Enumerations

Name

TCP_STATE ( see page

558)

Description

TCP States as defined by RFC 793

Functions

Name

TCPInit ( see page 559)

Description

Initializes the TCP module.

TCPProcess ( see page

559)

TCPTick ( see page 560)

Handles incoming TCP segments.

TCPSSLDecryptMAC ( see page 560)

TCPStartSSLClientEx ( see page 561)

Performs periodic TCP tasks.

Decrypts and MACs data arriving via SSL.

Begins an SSL client session.

Module

TCB_STUB ( see page 556) TCP Control Block (TCB) stub data storage. Stubs are stored in local PIC RAM

554

10.18 TCP Microchip TCP/IP Stack Help TCP Stack Members

Structures

Name

SOCKET_INFO ( see page

555)

TCB ( see page 555)

Description

Information about a socket

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)

for speed. Current size is 34 bytes (PIC18), 36 bytes (PIC24/dsPIC), or 56

(PIC32)

Types

Name

TCP_SOCKET ( see page

558)

Description

A TCP_SOCKET is stored as a single BYTE

Description

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.

10.18.2.1

SOCKET_INFO Structure

File

TCP.h

C typedef struct

{

NODE_INFO remote;

WORD_VAL remotePort;

} SOCKET_INFO;

Members

NODE_INFO remote;

WORD_VAL remotePort;

Description

Information about a socket

Description

NODE_INFO structure for remote node

Port number associated with remote node

10.18.2.2

TCB Structure

File

TCP.h

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;

555

10.18 TCP Microchip TCP/IP Stack Help TCP Stack Members

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;

Members

DWORD retryInterval;

DWORD MySEQ;

DWORD RemoteSEQ;

PTR_BASE txUnackedTail;

WORD_VAL remotePort;

WORD_VAL localPort;

WORD remoteWindow;

WORD wFutureDataSize;

NODE_INFO niRemoteMACIP;

DWORD dwRemoteHost;

SHORT sHoleSize; unsigned char bFINSent : 1; unsigned char bSYNSent : 1; unsigned char bRemoteHostIsROM : 1; unsigned char bRXNoneACKed1 : 1; unsigned char bRXNoneACKed2 : 1; unsigned char filler : 3;

WORD wRemoteMSS;

WORD_VAL localSSLPort;

BYTE retryCount;

BYTE vSocketPurpose;

Description

How long to wait before retrying transmission

Local sequence number

Remote sequence number

TX tail pointer for data that is not yet acked

Remote port number

Local port number

Remote window size

How much out-of-order data has been received

10 bytes for MAC and IP address

RAM or ROM pointer to a hostname string (ex: "www.microchip.com")

Size of the hole, or -1 for none exists. (0 indicates hole has just been filled)

A FIN has been sent

A SYN has been sent

Remote host is stored in ROM

A duplicate ACK was likely received

A second duplicate ACK was likely received future use

Maximum Segment Size option advirtised by the remote node during initial handshaking

Local SSL port number (for listening sockets)

Counter for transmission retries

Purpose of socket (as defined in TCPIPConfig.h)

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)

10.18.2.3

TCB_STUB Structure

File

TCP.h

C typedef struct

{

PTR_BASE bufferTxStart;

PTR_BASE bufferRxStart;

PTR_BASE bufferEnd;

556

10.18 TCP Microchip TCP/IP Stack Help TCP Stack Members

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;

Members

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;

WORD delayedACKTime;

WORD closeWaitTime;

TCP_STATE smState; unsigned char vUnackedKeepalives : 3; unsigned char bServer : 1;

Description

First byte of TX buffer

First byte of RX buffer. TX buffer ends 1 byte prior

Last byte of RX buffer

Head pointer for TX

Tail pointer for TX

Head pointer for RX

Tail pointer for RX

Packet retransmissions, state changes

Window updates, automatic transmission

Delayed Acknowledgement timer

TCP_CLOSE_WAIT timeout timer

State of this socket

Count of how many keepalives have been sent with no response

Socket should return to listening state when closed unsigned char bTimerEnabled : 1; unsigned char bTimer2Enabled : 1; unsigned char bDelayedACKTimerEnabled : 1;

DelayedACK timer is enabled unsigned char bOneSegmentReceived : 1; A segment has been received unsigned char bHalfFullFlush : 1;

Timer is enabled

Second timer is enabled unsigned char bTXASAP : 1; unsigned char bTXASAPWithoutTimerReset : 1;

Flush is for being half full

Transmit as soon as possible (for Flush)

Transmit as soon as possible (for Flush), but do not reset retransmission timers unsigned char bTXFIN : 1; FIN needs to be transmitted

557

10.18 TCP Microchip TCP/IP Stack Help TCP Stack Members unsigned char bSocketReset : 1; unsigned char bSSLHandshaking : 1; unsigned char filler : 2;

WORD_VAL remoteHash;

PTR_BASE sslTxHead;

PTR_BASE sslRxHead;

BYTE sslStubID;

BYTE sslReqMessage;

BYTE vMemoryMedium;

Socket has been reset (self-clearing semaphore)

Socket is in an SSL handshake

Future expansion

Consists of remoteIP, remotePort, localPort for connected sockets. It is a localPort number only for listening server sockets.

Position of data being written in next SSL application record Also serves as cache of localSSLPort when smState = TCP_LISTENING

Position of incoming data not yet handled by SSL

Which sslStub ( see page 523) is associated with this connection

Currently requested SSL message

Which memory medium the TCB is actually stored

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)

10.18.2.4

TCP_SOCKET Type

File

TCP.h

C typedef

BYTE TCP_SOCKET;

Description

A TCP_SOCKET is stored as a single BYTE

10.18.2.5

TCP_STATE Enumeration

File

TCP.h

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;

Members

TCP_GET_DNS_MODULE

TCP_DNS_RESOLVE

TCP_GATEWAY_SEND_ARP

Description

Special state for TCP client mode sockets

558

10.18 TCP

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

Description

TCP States as defined by RFC 793

Microchip TCP/IP Stack Help TCP Stack Members

Special state for TCP client mode sockets

Socket is listening for connections

A SYN has been sent, awaiting an SYN+ACK

A SYN has been received, awaiting an ACK

Socket is connected and connection is established

FIN WAIT state 1

FIN WAIT state 2

Socket is closing TCP_TIME_WAIT, state is not implemented

Waiting to close the socket

The final ACK has been sent

Socket is idle and unallocated

Special state for TCP client mode sockets. Socket is idle, but still allocated pending application closure of the handle.

10.18.2.6

TCPInit Function

File

TCP.h

C void

TCPInit();

Returns

None

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.

Remarks

This function is called only one during lifetime of the application.

Preconditions

None

Section

Function Declarations

10.18.2.7

TCPProcess Function

File

TCP.h

BOOL TCPProcess(

NODE_INFO* remote,

IP_ADDR* localIP,

WORD len

);

559

10.18 TCP Microchip TCP/IP Stack Help TCP Stack Members

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 ( see page 565) for further processing.

Preconditions

TCP is initialized and a TCP segment is ready in the MAC buffer.

Parameters

remote localIP len

Return Values

TRUE

FALSE

Description

Remote NODE_INFO structure

This stack's IP address (for header checking)

Total length of the waiting TCP segment

Description

the segment was properly handled.

otherwise

10.18.2.8

TCPTick Function

File

TCP.h

C void

TCPTick();

Returns

None

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.

10.18.2.9

TCPSSLDecryptMAC Function

File

TCP.h

C void

TCPSSLDecryptMAC(

ARCFOUR_CTX* ctx,

WORD len

);

Returns

None

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.

560

10.18 TCP Microchip TCP/IP Stack Help TCP Internal Members

Remarks

This function should never be called by an application. It is used only by the SSL module itself.

Preconditions

TCP is initialized, hTCP is connected, and ctx's Sbox is loaded.

Parameters

hTCP ctx len inPlace

Description

TCP connection to decrypt in

ARCFOUR encryption context to use

Number of bytes to crypt

TRUE to write back in place, FALSE to write at end of currently visible data.

10.18.2.10

TCPStartSSLClientEx Function

File

TCP.h

BOOL TCPStartSSLClientEx(

FindMatchingSocket ( see page 564)

BYTE* host,

void

* buffer,

BYTE suppDataType

);

Description

This function escalates the current connection to an SSL secured connection by initiating an SSL client handshake.

Remarks

The host parameter is currently ignored and is not validated.

Preconditions

TCP is initialized and hTCP is already connected.

Parameters

hTCP host buffer suppDataType

Return Values

TRUE

FALSE

Description

TCP connection to secure

Expected host name on certificate (currently ignored)

Buffer for supplementary data return

Type of supplementary data to copy

Description

an SSL connection was initiated

Insufficient SSL resources (stubs) were available

561

10.18 TCP Microchip TCP/IP Stack Help TCP Internal Members

10.18.3

TCP Internal Members

Functions

Name

CloseSocket ( see page

564)

Description

Closes a TCP socket.

HandleTCPSeg ( see page

565)

Finds a suitable socket for a TCP segment.

Processes an incoming TCP segment.

SendTCP ( see page 567)

Transmits a TPC segment.

SwapTCPHeader ( see page 568)

Swaps endian-ness of a TCP header.

SyncTCB ( see page 569)

Flushes MyTCB cache and loads up the specified TCB. Does nothing on cache hit.

Macros

Name

ACK ( see page 564)

FIN ( see page 564)

LOCAL_PORT_END_NUMBER ( see page 566)

LOCAL_PORT_START_NUMBER ( see page 566)

PSH ( see page 567)

RST ( see page 567)

SENDTCP_KEEP_ALIVE ( see page

568)

SENDTCP_RESET_TIMERS ( see page

568)

SYN ( see page 568)

SyncTCBStub ( see page 569)

Description

Acknowledge Flag as defined in RFC

FIN Flag as defined in RFC

End port for client sockets

Starting port for client sockets

Push Flag as defined in RFC

Reset Flag as defined in RFC

Instead of transmitting normal data, a garbage octet is transmitted according to RFC 1122 section 4.2.3.6

Indicates if this packet is a retransmission (no reset) or a new packet (reset required)

SYN Flag as defined in RFC

Flushes MyTCBStub ( see page 566) cache and loads up the

specified TCB_STUB ( see page 556). Does nothing on cache

hit.

TCP_AUTO_TRANSMIT_TIMEOUT_VAL

( see page 570)

Timeout before automatically transmitting unflushed data

TCP_WINDOW_UPDATE_TIMEOUT_VAL

( see page 570)

Timeout before automatically transmitting a window update due to

a TCPGet ( see page 542)() or TCPGetArray ( see page 543)()

function call

TCP_CLOSE_WAIT_TIMEOUT ( see page 570)

Timeout for the CLOSE_WAIT state

Timeout for delayed-acknowledgement algorithm

TCP_DELAYED_ACK_TIMEOUT ( see page 570)

TCP_FIN_WAIT_2_TIMEOUT ( see page 571)

TCP_KEEP_ALIVE_TIMEOUT ( see page 572)

TCP_MAX_RETRIES ( see page 572)

Timeout for FIN WAIT 2 state

Timeout for keep-alive messages when no traffic is sent

Maximum number of retransmission attempts

562

10.18 TCP Microchip TCP/IP Stack Help TCP Internal Members

TCP_MAX_SEG_SIZE_RX ( see page

572)

TCP_MAX_SEG_SIZE_TX ( see page

573)

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

Smaller than all other retries to reduce SYN flood DoS duration

TCP_MAX_SYN_RETRIES ( see page

573)

TCP_MAX_UNACKED_KEEP_ALIVES ( see page 573)

TCP_OPTIMIZE_FOR_SIZE ( see page

573)

Maximum number of keep-alive messages that can be sent without receiving a response before automatically closing the connection

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

End of List TCP Option Flag

TCP_OPTIONS_END_OF_LIST ( see page 574)

TCP_OPTIONS_MAX_SEG_SIZE ( see page 574)

TCP_SYN_QUEUE_MAX_ENTRIES ( see page 576)

TCP_SYN_QUEUE_TIMEOUT ( see page 576)

URG ( see page 576)

Maximum segment size TCP flag

TCP_OPTIONS_NO_OP ( see page 574) No Op TCP Option

TCP_SOCKET_COUNT ( see page 575)

Determines the number of defined TCP sockets

TCP_START_TIMEOUT_VAL ( see page 575)

Timeout to retransmit unacked data

Number of TCP RX SYN packets to save if they cannot be serviced immediately

Timeout for when SYN queue entries are deleted if unserviceable

Urgent Flag as defined in RFC

Module

TCP_SYN_QUEUE ( see page 575)

Structures

Name

TCP_HEADER ( see page

571)

TCP_OPTIONS ( see page

574)

Description

TCP Header Data Structure

TCP Options data structure

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

hCurrentTCP ( see page

565)

MyTCB ( see page 566)

Description

Current TCP socket

Currently loaded TCB

MyTCBStub ( see page 566) Alias to current TCP stub.

SYNQueue ( see page 569) Array of saved incoming SYN requests that need to be serviced later

563

10.18 TCP Microchip TCP/IP Stack Help

TCBStubs ( see page 569)

This is variable TCBStubs.

Description

The following functions and variables are designated as internal to the TCP module.

TCP Internal Members

10.18.3.1

ACK Macro

File

TCP.c

#define

ACK (0x10)

// Acknowledge Flag as defined in RFC

Description

Acknowledge Flag as defined in RFC

10.18.3.2

CloseSocket Function

File

TCP.c

C static void

CloseSocket();

Returns

None

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.

10.18.3.3

FIN Macro

File

TCP.c

#define

FIN (0x01)

// FIN Flag as defined in RFC

Description

FIN Flag as defined in RFC

10.18.3.4

FindMatchingSocket Function

File

TCP.c

C static

BOOL FindMatchingSocket(

564

10.18 TCP Microchip TCP/IP Stack Help TCP Internal Members

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 ( see page 565) and the associated MyTCBStub ( see page 566)

and MyTCB are loaded. Otherwise, INVALID_SOCKET ( see page 533) is placed in hCurrentTCP ( see page 565).

Preconditions

TCP is initialized.

Parameters

h remote

Return Values

TRUE

FALSE

Description

TCP header to be matched against

The remote node who sent this header

Description

A match was found and is loaded in hCurrentTCP ( see page 565)

No suitable socket was found and hCurrentTCP ( see page 565) is

INVALID_SOCKET ( see page 533)

10.18.3.5

HandleTCPSeg Function

File

TCP.c

C static void

HandleTCPSeg(

TCP_HEADER* h,

WORD len

);

Returns

None

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

h len

Description

The TCP header for this packet

The total buffer length of this segment

10.18.3.6

hCurrentTCP Variable

File

TCP.c

565

10.18 TCP Microchip TCP/IP Stack Help

TCP_SOCKET hCurrentTCP = INVALID_SOCKET;

Description

Current TCP socket

10.18.3.7

LOCAL_PORT_END_NUMBER Macro

File

TCP.c

#define

LOCAL_PORT_END_NUMBER (5000u)

Description

End port for client sockets

10.18.3.8

LOCAL_PORT_START_NUMBER Macro

File

TCP.c

#define

LOCAL_PORT_START_NUMBER (1024u)

Description

Starting port for client sockets

10.18.3.9

MyTCB Variable

File

TCP.c

TCB MyTCB;

Description

Currently loaded TCB

10.18.3.10

MyTCBStub Variable

File

TCP.c

TCB_STUB MyTCBStub;

Description

Alias to current TCP stub.

TCP Internal Members

566

10.18 TCP Microchip TCP/IP Stack Help TCP Internal Members

10.18.3.11

PSH Macro

File

TCP.c

#define

PSH (0x08)

// Push Flag as defined in RFC

Description

Push Flag as defined in RFC

10.18.3.12

RST Macro

File

TCP.c

#define

RST (0x04)

// Reset Flag as defined in RFC

Description

Reset Flag as defined in RFC

10.18.3.13

SendTCP Function

File

TCP.c

C static void

SendTCP(

BYTE vTCPFlags,

BYTE vSendFlags

);

Returns

None

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

vTCPFlags vSendFlags

Description

Additional TCP flags to include

Any combinations of SENDTCP_* constants to modify the transmit behavior or contents.

567

10.18 TCP Microchip TCP/IP Stack Help TCP Internal Members

10.18.3.14

SENDTCP_KEEP_ALIVE Macro

File

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

10.18.3.15

SENDTCP_RESET_TIMERS Macro

File

TCP.c

#define

SENDTCP_RESET_TIMERS 0x01

Description

Indicates if this packet is a retransmission (no reset) or a new packet (reset required)

10.18.3.16

SwapTCPHeader Function

File

TCP.c

C static void

SwapTCPHeader(

TCP_HEADER* header

);

Returns

None

Description

This function swaps the endian-ness of a given TCP header for comparison.

Preconditions

None

Parameters

header

Description

The TCP header that is to be swapped

10.18.3.17

SYN Macro

File

TCP.c

#define

SYN (0x02)

// SYN Flag as defined in RFC

568

10.18 TCP

Description

SYN Flag as defined in RFC

Microchip TCP/IP Stack Help TCP Internal Members

10.18.3.18

SyncTCB Function

File

TCP.c

C static void

SyncTCB();

Description

Flushes MyTCB cache and loads up the specified TCB. Does nothing on cache hit.

10.18.3.19

SyncTCBStub Macro

File

TCP.c

#define

SyncTCBStub(a) hCurrentTCP = (a)

Description

Flushes MyTCBStub ( see page 566) cache and loads up the specified TCB_STUB ( see page 556). Does nothing on

cache hit.

10.18.3.20

SYNQueue Variable

File

TCP.c

TCP_SYN_QUEUE SYNQueue[TCP_SYN_QUEUE_MAX_ENTRIES];

Description

Array of saved incoming SYN requests that need to be serviced later

10.18.3.21

TCBStubs Variable

File

TCP.c

TCB_STUB TCBStubs[TCP_SOCKET_COUNT];

Description

This is variable TCBStubs.

569

10.18 TCP Microchip TCP/IP Stack Help TCP Internal Members

10.18.3.22

TCP_AUTO_TRANSMIT_TIMEOUT_VAL Macro

File

TCP.c

#define

TCP_AUTO_TRANSMIT_TIMEOUT_VAL (TICK_SECOND/25ull)

// Timeout before automatically transmitting unflushed data

Description

Timeout before automatically transmitting unflushed data

10.18.3.23

TCP_WINDOW_UPDATE_TIMEOUT_VAL Macro

File

TCP.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 ( see page 542)() or TCPGetArray ( see page 543)() function call

10.18.3.24

TCP_CLOSE_WAIT_TIMEOUT Macro

File

TCP.c

#define

TCP_CLOSE_WAIT_TIMEOUT ((DWORD)TICK_SECOND/5)

// Timeout for the CLOSE_WAIT state

Description

Timeout for the CLOSE_WAIT state

10.18.3.25

TCP_DELAYED_ACK_TIMEOUT Macro

File

TCP.c

#define

TCP_DELAYED_ACK_TIMEOUT ((DWORD)TICK_SECOND/10)

// Timeout for delayed-acknowledgement algorithm

Description

Timeout for delayed-acknowledgement algorithm

570

10.18 TCP Microchip TCP/IP Stack Help TCP Internal Members

10.18.3.26

TCP_FIN_WAIT_2_TIMEOUT Macro

File

TCP.c

#define

TCP_FIN_WAIT_2_TIMEOUT ((DWORD)TICK_SECOND*5)

// Timeout for FIN WAIT 2 state

Description

Timeout for FIN WAIT 2 state

10.18.3.27

TCP_HEADER Structure

File

TCP.c

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;

Members

WORD SourcePort;

WORD DestPort;

DWORD SeqNumber;

DWORD AckNumber; struct { unsigned char Reserved3 : 4; unsigned char Val : 4;

} DataOffset;

Description

Local port number

Remote port number

Local sequence number

Acknowledging remote sequence number

Data offset flags nibble

571

10.18 TCP 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;

Description

TCP Header Data Structure

Microchip TCP/IP Stack Help

TCP Flags as defined in RFC

Local free RX buffer window

Data payload checksum

Urgent pointer

TCP Internal Members

10.18.3.28

TCP_KEEP_ALIVE_TIMEOUT Macro

File

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

10.18.3.29

TCP_MAX_RETRIES Macro

File

TCP.c

#define

TCP_MAX_RETRIES (5u)

// Maximum number of retransmission attempts

Description

Maximum number of retransmission attempts

10.18.3.30

TCP_MAX_SEG_SIZE_RX Macro

File

TCP.c

#define

TCP_MAX_SEG_SIZE_RX (536u)

Description

572

10.18 TCP Microchip TCP/IP Stack Help TCP Internal Members enhance performance at the (small) risk of introducing incompatibility with certain special remote nodes (ex: ones connected via a slow dial up modem).

10.18.3.31

TCP_MAX_SEG_SIZE_TX Macro

File

TCP.c

#define

TCP_MAX_SEG_SIZE_TX (1460u)

Description

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.

10.18.3.32

TCP_MAX_SYN_RETRIES Macro

File

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

10.18.3.33

TCP_MAX_UNACKED_KEEP_ALIVES Macro

File

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

10.18.3.34

TCP_OPTIMIZE_FOR_SIZE Macro

File

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

573

10.18 TCP Microchip TCP/IP Stack Help

On PIC32 products there is very little difference and depnds on compiler optimization level

10.18.3.35

TCP_OPTIONS Structure

File

TCP.c

C typedef struct

{

BYTE Kind;

BYTE Length;

WORD_VAL MaxSegSize;

} TCP_OPTIONS;

Members

BYTE Kind;

BYTE Length;

WORD_VAL MaxSegSize;

Description

TCP Options data structure

Description

Type of option

Length

Maximum segment size

TCP Internal Members

10.18.3.36

TCP_OPTIONS_END_OF_LIST Macro

File

TCP.c

#define

TCP_OPTIONS_END_OF_LIST (0x00u)

// End of List TCP Option Flag

Description

End of List TCP Option Flag

10.18.3.37

TCP_OPTIONS_MAX_SEG_SIZE Macro

File

TCP.c

#define

TCP_OPTIONS_MAX_SEG_SIZE (0x02u)

// Maximum segment size TCP flag

Description

Maximum segment size TCP flag

10.18.3.38

TCP_OPTIONS_NO_OP Macro

File

TCP.c

#define

TCP_OPTIONS_NO_OP (0x01u)

// No Op TCP Option

574

10.18 TCP

Description

No Op TCP Option

Microchip TCP/IP Stack Help TCP Internal Members

10.18.3.39

TCP_SOCKET_COUNT Macro

File

TCP.c

#define

TCP_SOCKET_COUNT (

sizeof

(TCPSocketInitializer)/

sizeof

(TCPSocketInitializer[0]))

Description

Determines the number of defined TCP sockets

10.18.3.40

TCP_START_TIMEOUT_VAL Macro

File

TCP.c

#define

TCP_START_TIMEOUT_VAL ((DWORD)TICK_SECOND*1)

// Timeout to retransmit unacked data

Description

Timeout to retransmit unacked data

10.18.3.41

TCP_SYN_QUEUE Structure

File

TCP.c

C typedef struct

{

NODE_INFO niSourceAddress;

WORD wSourcePort;

DWORD dwSourceSEQ;

WORD wDestPort;

WORD wTimestamp;

} TCP_SYN_QUEUE;

Members

NODE_INFO niSourceAddress;

WORD wSourcePort;

DWORD dwSourceSEQ;

WORD wDestPort;

WORD wTimestamp;

Description

Remote IP address and MAC address

Remote TCP port number that the response SYN needs to be sent to

Remote TCP SEQuence number that must be ACKnowledged when we send our response SYN

Local TCP port which the original SYN was destined for

Timer to expire old SYN packets that can't be serviced at all

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

575

10.18 TCP Microchip TCP/IP Stack Help Functions

10.18.3.42

TCP_SYN_QUEUE_MAX_ENTRIES Macro

File

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

10.18.3.43

TCP_SYN_QUEUE_TIMEOUT Macro

File

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

10.18.3.44

URG Macro

File

TCP.c

#define

URG (0x20)

// Urgent Flag as defined in RFC

Description

Urgent Flag as defined in RFC

10.18.4

Functions

Functions

Name

WFGetTCBSize ( see page

576)

Description

This is function WFGetTCBSize.

Module

10.18.4.1

WFGetTCBSize Function

File

TCP.c

576

10.19 Telnet

UINT16 WFGetTCBSize();

Description

This is function WFGetTCBSize.

Microchip TCP/IP Stack Help

10.18.5

Variables

Module

TelnetTask ( see page 580)

Variables

Name

NextPort ( see page 577)

Description

Tracking variable for next local client port number

10.18.5.1

NextPort Variable

File

TCP.c

WORD NextPort;

Description

Tracking variable for next local client port number

Telnet Public Members

10.19

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

function to include the functionality you'd like. You may

insert or change states in

TelnetTask ( see page 580)

as needed.

577

10.19 Telnet Microchip TCP/IP Stack Help Telnet Public Members

10.19.1

Telnet Public Members

Macros

Name Description

MAX_TELNET_CONNECTIONS

( see page 578)

Number of simultaneously allowed Telnet ( see page 577) 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.

Default Telnet ( see page 577) password

TELNET_PASSWORD ( see page 578)

TELNET_PORT ( see page

579)

TELNETS_PORT ( see page

579)

TELNET_USERNAME ( see page 579)

Default local listening port for the Telnet ( see page 577) server. Port 23 is

the protocol default.

Default local listening port for the Telnet ( see page 577) server when SSL

secured. Port 992 is the telnets protocol default.

Default username and password required to login to the Telnet ( see page

577) server.

Module

Number of simultaneously allowed Telnet ( see page 577) sessions. Note that you must have an equal number of

Description

The following functions and variables are available to the stack application.

10.19.1.1

MAX_TELNET_CONNECTIONS Macro

File

TCPIP MRF24W.h

#define

MAX_TELNET_CONNECTIONS (1u)

Description

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.

10.19.1.2

TELNET_PASSWORD Macro

File

TCPIP MRF24W.h

#define

TELNET_PASSWORD "microchip"

Description

Default Telnet ( see page 577) password

578

10.19 Telnet Microchip TCP/IP Stack Help Telnet Stack Members

10.19.1.3

TELNET_PORT Macro

File

TCPIP MRF24W.h

#define

TELNET_PORT 23

Description

Default local listening port for the Telnet ( see page 577) server. Port 23 is the protocol default.

10.19.1.4

TELNETS_PORT Macro

File

TCPIP MRF24W.h

#define

TELNETS_PORT 992

Description

Default local listening port for the Telnet ( see page 577) server when SSL secured. Port 992 is the telnets protocol default.

10.19.1.5

TELNET_USERNAME Macro

File

TCPIP MRF24W.h

#define

TELNET_USERNAME "admin"

Description

Default username and password required to login to the Telnet ( see page 577) server.

10.19.2

Telnet Stack Members

Functions

Name Description

TelnetTask ( see page 580) Performs Telnet ( see page 577) Server related tasks. Contains the Telnet ( see page 577) state machine and state tracking variables.

Module

Performs Telnet ( see page 577) Server related tasks. Contains the Telnet ( see page 577) state machine and state

Description

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.

579

10.19 Telnet Microchip TCP/IP Stack Help Telnet Internal Members

10.19.2.1

TelnetTask Function

File

Telnet.h

C void

TelnetTask();

Side Effects

None

Returns

None

Description

tracking variables.

Remarks

None

Preconditions

Stack is initialized()

10.19.3

Telnet Internal Members

Module

strSpaces ( see page 580)

Variables

Name Description

String with extra spaces, for Demo

strAuthenticated ( see page

581)

Successful authentication message

strDisplay ( see page 581)

Demo output string

strGoodBye ( see page 581) Demo disconnection message strPassword ( see page

581)

strTitle ( see page 582)

DO Suppress Local Echo (stop telnet client from printing typed characters)

Access denied message

Demo title string

Description

The following functions and variables are designated as internal to the Telnet ( see page 577) module.

10.19.3.1

strSpaces Variable

File

Telnet.c

ROM BYTE strSpaces[] = " ";

580

10.19 Telnet

Description

String with extra spaces, for Demo

Microchip TCP/IP Stack Help Telnet Internal Members

10.19.3.2

strAuthenticated Variable

File

Telnet.c

ROM BYTE strAuthenticated[] = "\r\nLogged in successfully\r\n\r\n" "\r\nPress 'q' to quit\r\n";

Description

Successful authentication message

10.19.3.3

strDisplay Variable

File

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

10.19.3.4

strGoodBye Variable

File

Telnet.c

ROM BYTE strGoodBye[] = "\r\n\r\nGoodbye!\r\n";

Description

Demo disconnection message

10.19.3.5

strPassword Variable

File

Telnet.c

ROM BYTE strPassword[] = "Password: \xff\xfd\x2d";

Description

DO Suppress Local Echo (stop telnet client from printing typed characters) Access denied message

581

10.20 TFTP Microchip TCP/IP Stack Help

10.19.3.6

strTitle Variable

File

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

10.20

TFTP

The Trivial File Transfer Protocol provides unreliable upload and download services to applications connected to the

UDP-based TFTP server.

582

10.20 TFTP Microchip TCP/IP Stack Help TFTP Public Members

10.20.1

TFTP Public Members

Enumerations

Name

TFTP_ACCESS_ERROR ( see page 592)

_TFTP_ACCESS_ERROR

( see page 592)

TFTP_FILE_MODE ( see page 592)

_TFTP_FILE_MODE ( see page 592)

TFTP_RESULT ( see page

593)

Description

Standard error codes as defined by TFTP spec. Use to decode value retuned

by TFTPGetError ( see page 586)().

Standard error codes as defined by TFTP spec. Use to decode value retuned

by TFTPGetError ( see page 586)().

File open mode as used by TFTPFileOpen().

Enum. of results returned by most of the TFTP functions.

583

10.20 TFTP

_TFTP_RESULT ( see page 593)

Microchip TCP/IP Stack Help

Enum. of results returned by most of the TFTP functions.

TFTP Public Members

Functions

Name

TFTPCloseFile ( see page 585)

TFTPGet ( see page 586)

TFTPIsFileClosed ( see page 587)

Description

Sends file closing messages.

Gets a data byte from data that was read.

Determines if the file was closed.

TFTPIsFileOpened ( see page 587)

TFTPIsGetReady ( see page 588)

TFTPIsOpened ( see page 589)

Determines if file has been opened.

Determines if a data block is ready to be read.

Determines if the TFTP connection is open.

TFTPIsPutReady ( see page 589)

TFTPOpen ( see page 590)

TFTPOpenFile ( see page 591)

Determines if data can be written to a file.

Initializes TFTP module.

Prepares and sends TFTP file name and mode packet.

TFTPOpenROMFile ( see page 591) PIC18 ROM argument implementation of TFTPOpenFile ( see page 591)

Write a byte to a file.

TFTPPut ( see page 592)

TFTPGetUploadStatus ( see page 593) Returns the TFTP file upload status started by calling the

TFTPUploadRAMFileToHost ( see page 595)() or

TFTPUploadFragmentedRAMFileToHost ( see page 594)()

functions.

TFTPUploadFragmentedRAMFileToHost

( see page 594)

Uploads an random, potentially non-contiguous, array of RAM bytes as a file to a remote TFTP server.

TFTPUploadRAMFileToHost ( see page 595)

Uploads a contiguous array of RAM bytes as a file to a remote TFTP server.

Macros

Name

TFTPClose ( see page 585)

TFTPGetError ( see page 586)

TFTPIsFileOpenReady ( see page 588)

Description

Macro: void TFTPClose(void)

Closes TFTP client socket.

Macro: WORD TFTPGetError(void)

Returns previously saved error code.

Macro: BOOL TFTPIsFileOpenReady(void)

Checks to see if it is okay to send TFTP file open request to remote server.

TFTP_UPLOAD_COMPLETE ( see page

596)

Status codes for TFTPGetUploadStatus ( see page 593)()

function. Zero means upload success, >0 means working and

<0 means fatal error.

TFTP_UPLOAD_CONNECT ( see page 596) This is macro TFTP_UPLOAD_CONNECT.

TFTP_UPLOAD_CONNECT_TIMEOUT ( see page 596)

This is macro TFTP_UPLOAD_CONNECT_TIMEOUT.

TFTP_UPLOAD_GET_DNS ( see page 596)

This is macro TFTP_UPLOAD_GET_DNS.

TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT

( see page 597)

This is macro TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT.

TFTP_UPLOAD_RESOLVE_HOST ( see page 597)

This is macro TFTP_UPLOAD_RESOLVE_HOST.

584

10.20 TFTP Microchip TCP/IP Stack Help TFTP Public Members

TFTP_UPLOAD_SEND_DATA ( see page

597)

TFTP_UPLOAD_SEND_FILENAME ( see page 597)

TFTP_UPLOAD_SERVER_ERROR ( see page 597)

TFTP_UPLOAD_WAIT_FOR_CLOSURE ( see page 598)

Module

Once closed, application must do TFTPOpen ( see page 590) to perform any new TFTP operations.

This is macro TFTP_UPLOAD_SEND_DATA.

This is macro TFTP_UPLOAD_SEND_FILENAME.

This is macro TFTP_UPLOAD_SERVER_ERROR.

This is macro TFTP_UPLOAD_WAIT_FOR_CLOSURE.

Structures

Name Description

TFTP_CHUNK_DESCRIPTOR

( see page 595)

This is type TFTP_CHUNK_DESCRIPTOR.

Description

The following functions and variables are available to the stack application.

10.20.1.1

TFTPClose Macro

File

TFTPc.h

#define

TFTPClose(

void

) UDPClose(_tftpSocket)

Side Effects

None

Returns

None

Description

Macro: void TFTPClose(void)

Closes TFTP client socket.

Remarks

If TFTP server does not change during application life-time, one may not need to call TFTPClose and keep TFTP socket open.

Preconditions

TFTPOpen ( see page 590) is already called and TFTPIsOpened ( see page 589)() returned TFTP_OK.

10.20.1.2

TFTPCloseFile Function

File

TFTPc.h

C void

TFTPCloseFile();

585

10.20 TFTP Microchip TCP/IP Stack Help TFTP Public Members

Side Effects

None

Returns

None

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.

Remarks

TFTPIsFileClosed ( see page 587)() must be called to confirm if file was really closed.

Preconditions

TFTPOpenFile ( see page 591)() was called and TFTPIsFileOpened ( see page 587)() had returned with TFTP_OK.

10.20.1.3

TFTPGet Function

File

TFTPc.h

BYTE TFTPGet();

Side Effects

None

Returns

data byte as received from remote server.

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.

Remarks

Use this function to read file from server.

Preconditions

TFTPOpenFile ( see page 591)() is called with TFTP_FILE_MODE_READ and TFTPIsGetReady ( see page 588)() =

TRUE

10.20.1.4

TFTPGetError Macro

File

TFTPc.h

#define

TFTPGetError (_tftpError)

Side Effects

None

Returns

Error code as returned by remote server. Application may use TFTP_ACCESS_ERROR ( see page 592) enum. to decode

standard error code.

586

10.20 TFTP Microchip TCP/IP Stack Help

Description

Macro: WORD TFTPGetError(void)

Returns previously saved error code.

Remarks

None

Preconditions

One of the TFTP function returned with TFTP_ERROR result.

TFTP Public Members

10.20.1.5

TFTPIsFileClosed Function

File

TFTPc.h

TFTP_RESULT TFTPIsFileClosed();

Side Effects

None

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 ( see page 586)()

TFTP_NOT_READY if file is not closed yet.

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.

Remarks

None

Preconditions

TFTPCloseFile ( see page 585)() is already called.

10.20.1.6

TFTPIsFileOpened Function

File

TFTPc.h

TFTP_RESULT TFTPIsFileOpened();

Side Effects

None

587

10.20 TFTP Microchip TCP/IP Stack Help TFTP Public Members

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.

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

Remarks

None

Preconditions

TFTPOpenFile ( see page 591)() is called.

10.20.1.7

TFTPIsFileOpenReady Macro

File

TFTPc.h

#define

TFTPIsFileOpenReady UDPIsPutReady(_tftpSocket)

Side Effects

None

Returns

TRUE, if it is ok to call TFTPOpenFile ( see page 591)() FALSE, if otherwise.

Description

Macro: BOOL TFTPIsFileOpenReady(void)

Checks to see if it is okay to send TFTP file open request to remote server.

Remarks

None

Preconditions

TFTPOpen ( see page 590) is already called and TFTPIsOpened ( see page 589)() returned TFTP_OK.

10.20.1.8

TFTPIsGetReady Function

File

TFTPc.h

TFTP_RESULT TFTPIsGetReady();

Side Effects

None

588

10.20 TFTP Microchip TCP/IP Stack Help TFTP Public Members

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 ( see page

586)()

TFTP_NOT_READY if still waiting for new data.

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.

Remarks

By default, this funciton uses "octet" or binary mode of file transfer.

Preconditions

TFTPOpenFile ( see page 591)() is called with TFTP_FILE_MODE_READ and TFTPIsFileOpened ( see page 587)()

returned with TRUE.

10.20.1.9

TFTPIsOpened Function

File

TFTPc.h

TFTP_RESULT TFTPIsOpened();

Side Effects

None

Returns

TFTP_OK if previous call to TFTPOpen ( see page 590) 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.

Description

Waits for ARP reply and opens a UDP socket to perform further TFTP operations.

Remarks

Once opened, application may keep TFTP socket open and future TFTP operations. If TFTPClose ( see page 585)() is

called to close the connection TFTPOpen ( see page 590)() must be called again before performing any other TFTP

operations.

Preconditions

TFTPOpen ( see page 590)() is already called.

10.20.1.10

TFTPIsPutReady Function

File

TFTPc.h

589

10.20 TFTP Microchip TCP/IP Stack Help TFTP Public Members

TFTP_RESULT TFTPIsPutReady();

Side Effects

None

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 ( see page

586)()

TFTP_NOT_READY if still waiting...

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.

Remarks

None

Preconditions

TFTPOpenFile ( see page 591)() is called with TFTP_FILE_MODE_WRITE and TFTPIsFileOpened ( see page 587)()

returned with TRUE.

10.20.1.11

TFTPOpen Function

File

TFTPc.h

C void

TFTPOpen(

IP_ADDR * host

);

Side Effects

None

Returns

None

Description

Initiates ARP for given host and prepares TFTP module for next sequence of function calls.

Remarks

Use TFTPIsOpened ( see page 589)() to check if a connection was successfully opened or not.

Preconditions

UDP module is already initialized and at least one UDP socket is available.

590

10.20 TFTP

Parameters

host

Microchip TCP/IP Stack Help

Description

IP address of remote TFTP server

TFTP Public Members

10.20.1.12

TFTPOpenFile Function

File

TFTPc.h

C void

TFTPOpenFile(

BYTE * fileName,

TFTP_FILE_MODE mode

);

Side Effects

None

Returns

None

Description

Prepares and sends TFTP file name and mode packet.

Remarks

By default, this funciton uses "octet" or binary mode of file transfer. Use TFTPIsFileOpened ( see page 587)() to check if

file is ready to be read or written.

Preconditions

TFPTIsFileOpenReady() = TRUE

Parameters

fileName mode

Description

File name that is to be opened.

Mode of file access Must be TFTP_FILE_MODE_READ for read

TFTP_FILE_MODE_WRITE for write

10.20.1.13

TFTPOpenROMFile Function

File

TFTPc.h

C void

TFTPOpenROMFile(

ROM BYTE * fileName,

TFTP_FILE_MODE mode

);

Description

PIC18 ROM argument implementation of TFTPOpenFile ( see page 591)

591

10.20 TFTP Microchip TCP/IP Stack Help TFTP Public Members

10.20.1.14

TFTPPut Function

File

TFTPc.h

C void

TFTPPut(

BYTE c

);

Side Effects

None

Returns

None

Description

Puts given data byte into TFTP socket. If end of data block is reached, it transmits entire block.

Remarks

Use this function to write file to server.

Preconditions

TFTPOpenFile ( see page 591)() is called with TFTP_FILE_MODE_WRITE and TFTPIsPutReady ( see page 589)() =

TRUE

Parameters

Description

Data byte that is to be written

10.20.1.15

TFTP_ACCESS_ERROR Enumeration

File

TFTPc.h

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 ( see page 586)().

10.20.1.16

TFTP_FILE_MODE Enumeration

File

TFTPc.h

592

10.20 TFTP

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

Microchip TCP/IP Stack Help TFTP Public Members

10.20.1.17

TFTP_RESULT Enumeration

File

TFTPc.h

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.

10.20.1.18

TFTPGetUploadStatus Function

File

TFTPc.h

CHAR TFTPGetUploadStatus();

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 ( see page 596)): Upload completed successfully 1

(TFTP_UPLOAD_GET_DNS ( see page 596)):

Attempting to obtain DNS client module 2

(TFTP_UPLOAD_RESOLVE_HOST ( see page 597)):

Attempting to resolve TFTP hostname 3

(TFTP_UPLOAD_CONNECT ( see page 596)): Attempting to ARP and contact the TFTP server 4

(TFTP_UPLOAD_SEND_FILENAME ( see page 597)): Attempting to send the filename and receive acknowledgement. 5

(TFTP_UPLOAD_SEND_DATA ( see page 597)): Attempting to send the file contents and receive acknowledgement. 6

(TFTP_UPLOAD_WAIT_FOR_CLOSURE ( see page 598)): Attempting to send the final packet of file contents and receive

acknowledgement. -1 (TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT ( see page 597)): Couldn't resolve hostname -2

(TFTP_UPLOAD_CONNECT_TIMEOUT ( see page 596)):

Couldn't finish ARP and reach server -3

(TFTP_UPLOAD_SERVER_ERROR ( see page 597)): TFTP server returned an error (ex: access denial) or file upload

failed due to a timeout (partial file may have been uploaded).

Description

Returns the TFTP file upload status started by calling the TFTPUploadRAMFileToHost ( see page 595)() or

TFTPUploadFragmentedRAMFileToHost ( see page 594)() functions.

Remarks

The DNS client module must be enabled to use this function. i.e. STACK_USE_DNS must be defined in TCPIPConfig.h.

593

10.20 TFTP

Preconditions

None

Microchip TCP/IP Stack Help TFTP Public Members

10.20.1.19

TFTPUploadFragmentedRAMFileToHost Function

File

TFTPc.h

C void

TFTPUploadFragmentedRAMFileToHost(

ROM BYTE * vRemoteHost,

ROM BYTE * vFilename,

TFTP_CHUNK_DESCRIPTOR * vFirstChunkDescriptor

);

Returns

None

Description

Uploads an random, potentially non-contiguous, array of RAM bytes as a file to a remote TFTP server.

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 ( see page 593)() 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 ( see page 595)() or TFTPUploadFragmentedRAMFileToHost(), you must wait until

TFTPGetUploadStatus ( see page 593)() returns a completion status code (<=0) before calling any other TFTP API

functions.

Preconditions

None

Parameters

vRemoteHost vFilename vFirstChunkDescriptor

Description

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 ( see page 593)()).

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 ( see page 593)()).

Pointer to a static or global (persistent) array of TFTP_CHUNK_DESCRIPTOR

( see page 595) 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

( see page 595) array must be terminated by a dummy descriptor whos

TFTP_CHUNK_DESCRIPTOR.vDataPointer pointer is set to NULL. Refer to

the TFTPUploadRAMFileToHost ( see page 595)() API for an example calling

sequence since it merely a wrapper to this

TFTPUploadFragmentedRAMFileToHost() function.

594

10.20 TFTP Microchip TCP/IP Stack Help TFTP Public Members

10.20.1.20

TFTPUploadRAMFileToHost Function

File

TFTPc.h

C void

TFTPUploadRAMFileToHost(

ROM BYTE * vRemoteHost,

ROM BYTE * vFilename,

BYTE * vData,

WORD wDataLength

);

Returns

None

Description

Uploads a contiguous array of RAM bytes as a file to a remote TFTP server.

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 ( see page 593)() 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 ( see page 594)(), you must wait until

TFTPGetUploadStatus ( see page 593)() returns a completion status code (<=0) before calling any other TFTP API

functions.

Preconditions

None

Parameters

vRemoteHost vFilename vData wDataLength

Description

ROM string of the remote TFTP server to upload to (ex: "www.myserver.com").

TFTPGetUploadStatus ( see page 593)()).

Pointer to a RAM array of data to write to the file.

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 ( see page 594)() function instead.

10.20.1.21

TFTP_CHUNK_DESCRIPTOR Structure

File

TFTPc.h

C typedef struct

{

595

10.20 TFTP

BYTE * vDataPointer;

WORD wDataLength;

} TFTP_CHUNK_DESCRIPTOR;

Description

This is type TFTP_CHUNK_DESCRIPTOR.

Microchip TCP/IP Stack Help TFTP Public Members

10.20.1.22

TFTP_UPLOAD_COMPLETE Macro

File

TFTPc.h

#define

TFTP_UPLOAD_COMPLETE 0

Description

Status codes for TFTPGetUploadStatus ( see page 593)() function. Zero means upload success, >0 means working and

<0 means fatal error.

10.20.1.23

TFTP_UPLOAD_CONNECT Macro

File

TFTPc.h

#define

TFTP_UPLOAD_CONNECT 3

Description

This is macro TFTP_UPLOAD_CONNECT.

10.20.1.24

TFTP_UPLOAD_CONNECT_TIMEOUT Macro

File

TFTPc.h

#define

TFTP_UPLOAD_CONNECT_TIMEOUT -2

Description

This is macro TFTP_UPLOAD_CONNECT_TIMEOUT.

10.20.1.25

TFTP_UPLOAD_GET_DNS Macro

File

TFTPc.h

#define

TFTP_UPLOAD_GET_DNS 1

Description

This is macro TFTP_UPLOAD_GET_DNS.

596

10.20 TFTP Microchip TCP/IP Stack Help TFTP Public Members

10.20.1.26

TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT Macro

File

TFTPc.h

#define

TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT -1

Description

This is macro TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT.

10.20.1.27

TFTP_UPLOAD_RESOLVE_HOST Macro

File

TFTPc.h

#define

TFTP_UPLOAD_RESOLVE_HOST 2

Description

This is macro TFTP_UPLOAD_RESOLVE_HOST.

10.20.1.28

TFTP_UPLOAD_SEND_DATA Macro

File

TFTPc.h

#define

TFTP_UPLOAD_SEND_DATA 5

Description

This is macro TFTP_UPLOAD_SEND_DATA.

10.20.1.29

TFTP_UPLOAD_SEND_FILENAME Macro

File

TFTPc.h

#define

TFTP_UPLOAD_SEND_FILENAME 4

Description

This is macro TFTP_UPLOAD_SEND_FILENAME.

10.20.1.30

TFTP_UPLOAD_SERVER_ERROR Macro

File

TFTPc.h

597

10.20 TFTP Microchip TCP/IP Stack Help

#define

TFTP_UPLOAD_SERVER_ERROR -3

Description

This is macro TFTP_UPLOAD_SERVER_ERROR.

TFTP Stack Members

10.20.1.31

TFTP_UPLOAD_WAIT_FOR_CLOSURE Macro

File

TFTPc.h

#define

TFTP_UPLOAD_WAIT_FOR_CLOSURE 6

Description

This is macro TFTP_UPLOAD_WAIT_FOR_CLOSURE.

10.20.2

TFTP Stack Members

Macros

Name

TFTP_MAX_RETRIES ( see page 599)

Description

Number of seconds to wait before declaring TIMEOUT error on Put

Number of seconds to wait before declaring TIMEOUT error on Get.

Number of attempts before declaring TIMEOUT error.

Module

TFTP_ARP_TIMEOUT_VAL (3u * TICKS_PER_SECOND)

Description

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.

10.20.2.1

TFTP_ARP_TIMEOUT_VAL Macro

File

TFTPc.h

#define

Description

Number of seconds to wait before declaring TIMEOUT error on Put

598

10.20 TFTP Microchip TCP/IP Stack Help

10.20.2.2

TFTP_GET_TIMEOUT_VAL Macro

File

TFTPc.h

#define

TFTP_GET_TIMEOUT_VAL (3u * TICKS_PER_SECOND)

Description

Number of seconds to wait before declaring TIMEOUT error on Get.

10.20.2.3

TFTP_MAX_RETRIES Macro

File

TFTPc.h

#define

TFTP_MAX_RETRIES (3u)

Description

Number of attempts before declaring TIMEOUT error.

TFTP Internal Members

10.20.3

TFTP Internal Members

Enumerations

Name

TFTP_STATE ( see page

602)

Description

TFTP_OPCODE ( see page

601)

Enumeration of TFTP opcodes

The TFTP state machine

Functions

Name

_TFTPSendAck ( see page

603)

_TFTPSendFileName ( see page 603)

_TFTPSendROMFileName

( see page 604)

Description

Private helper function

PIC18 ROM variable argument implementation of _TFTPSendFileName ( see page 603)

Macros

Name

TFTP_BLOCK_SIZE ( see page 601)

TFTP_BLOCK_SIZE_MSB

( see page 601)

TFTP_CLIENT_PORT ( see page 601)

TFTP_SERVER_PORT ( see page 602)

Description

The size of a TFTP block - 512 bytes

The MSB of the TFTP_BLOCK_SIZE ( see page 601)

The TFTP Client port - a unique port on this device

The TFTP Server Port

599

10.20 TFTP Microchip TCP/IP Stack Help TFTP Internal Members

Module

_tftpError ( see page 602)

Variables

Name

MutExVar ( see page 600)

_tftpFlags ( see page 602)

_tftpRetries ( see page 603)

_tftpSocket ( see page 604)

_tftpStartTick ( see page 604)

Description

Mutually Exclusive variable groups to conserve RAM.

Variable to preserve error condition causes for later transmission

TFTP status flags

Tracker variable for the number of TFTP retries

TFTP Socket for TFTP server link

Timing variable used to detect timeout conditions

_tftpState ( see page 604) smUpload ( see page 604)

TFTP state machine tracker variable

This is variable smUpload.

uploadChunkDescriptor ( see page

605)

This is variable uploadChunkDescriptor.

uploadChunkDescriptorForRetransmit

( see page 605)

This is variable uploadChunkDescriptorForRetransmit.

vUploadFilename ( see page 605)

This is variable vUploadFilename.

vUploadRemoteHost ( see page

605)

TFTPUploadRAMFileToHost ( see page 595)(),

TFTPUploadFragmentedRAMFileToHost ( see page 594)() and

TFTPGetUploadStatus ( see page 593)() 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.

This is variable wUploadChunkOffset.

wUploadChunkOffset ( see page

606) wUploadChunkOffsetForRetransmit

( see page 606)

This is variable wUploadChunkOffsetForRetransmit.

Description

The following functions and variables are designated as internal to the TFTP module.

10.20.3.1

MutExVar Variable

File

TFTPc.c

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.

600

10.20 TFTP Microchip TCP/IP Stack Help

10.20.3.2

TFTP_BLOCK_SIZE Macro

File

TFTPc.c

#define

TFTP_BLOCK_SIZE (0x200L)

Description

The size of a TFTP block - 512 bytes

10.20.3.3

TFTP_BLOCK_SIZE_MSB Macro

File

TFTPc.c

#define

TFTP_BLOCK_SIZE_MSB (0x02u)

Description

The MSB of the TFTP_BLOCK_SIZE ( see page 601)

10.20.3.4

TFTP_CLIENT_PORT Macro

File

TFTPc.c

#define

TFTP_CLIENT_PORT 65352L

Description

The TFTP Client port - a unique port on this device

10.20.3.5

TFTP_OPCODE Enumeration

File

TFTPc.c

C typedef enum

{

TFTP_OPCODE_RRQ = 1,

TFTP_OPCODE_WRQ,

TFTP_OPCODE_DATA,

TFTP_OPCODE_ACK,

TFTP_OPCODE_ERROR

} TFTP_OPCODE;

Members

TFTP_OPCODE_RRQ = 1

TFTP_OPCODE_WRQ

TFTP_OPCODE_DATA

Description

Get

Put

Actual data

TFTP Internal Members

601

10.20 TFTP

TFTP_OPCODE_ACK

TFTP_OPCODE_ERROR

Description

Enumeration of TFTP opcodes

Microchip TCP/IP Stack Help

Ack for Get/Put

Error

10.20.3.6

TFTP_SERVER_PORT Macro

File

TFTPc.c

#define

TFTP_SERVER_PORT (69L)

Description

The TFTP Server Port

10.20.3.7

TFTP_STATE Enumeration

File

TFTPc.c

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

10.20.3.8

_tftpError Variable

File

TFTPc.c

WORD _tftpError;

Description

Variable to preserve error condition causes for later transmission

10.20.3.9

_tftpFlags Variable

File

TFTPc.c

TFTP Internal Members

602

10.20 TFTP

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

Microchip TCP/IP Stack Help

10.20.3.10

_tftpRetries Variable

File

TFTPc.c

BYTE _tftpRetries;

Description

Tracker variable for the number of TFTP retries

10.20.3.11

_TFTPSendAck Function

File

TFTPc.c

C static void

_TFTPSendAck(

WORD_VAL blockNumber

);

Description

Private helper function

10.20.3.12

_TFTPSendFileName Function

File

TFTPc.c

C static void

_TFTPSendFileName(

TFTP_OPCODE command,

BYTE * fileName

);

Description

Private helper function

TFTP Internal Members

603

10.20 TFTP Microchip TCP/IP Stack Help

10.20.3.13

_TFTPSendROMFileName Function

File

TFTPc.c

C static void

_TFTPSendROMFileName(

TFTP_OPCODE opcode,

ROM BYTE * fileName

);

Description

PIC18 ROM variable argument implementation of _TFTPSendFileName ( see page 603)

10.20.3.14

_tftpSocket Variable

File

TFTPc.c

UDP_SOCKET _tftpSocket = TFTP_UPLOAD_COMPLETE;

Description

TFTP Socket for TFTP server link

10.20.3.15

_tftpStartTick Variable

File

TFTPc.c

DWORD _tftpStartTick;

Description

Timing variable used to detect timeout conditions

10.20.3.16

_tftpState Variable

File

TFTPc.c

TFTP_STATE _tftpState;

Description

TFTP state machine tracker variable

10.20.3.17

smUpload Variable

File

TFTPc.c

TFTP Internal Members

604

10.20 TFTP Microchip TCP/IP Stack Help

CHAR smUpload = TFTP_UPLOAD_COMPLETE;

Description

This is variable smUpload.

TFTP Internal Members

10.20.3.18

uploadChunkDescriptor Variable

File

TFTPc.c

TFTP_CHUNK_DESCRIPTOR * uploadChunkDescriptor;

Description

This is variable uploadChunkDescriptor.

10.20.3.19

uploadChunkDescriptorForRetransmit Variable

File

TFTPc.c

TFTP_CHUNK_DESCRIPTOR * uploadChunkDescriptorForRetransmit;

Description

This is variable uploadChunkDescriptorForRetransmit.

10.20.3.20

vUploadFilename Variable

File

TFTPc.c

ROM BYTE * vUploadFilename;

Description

This is variable vUploadFilename.

10.20.3.21

vUploadRemoteHost Variable

File

TFTPc.c

ROM BYTE * vUploadRemoteHost;

Description

TFTPUploadRAMFileToHost (

see page 595)(), TFTPUploadFragmentedRAMFileToHost ( see page 594)() and

TFTPGetUploadStatus ( see page 593)() 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.

605

10.21 Tick Module Microchip TCP/IP Stack Help

10.20.3.22

wUploadChunkOffset Variable

File

TFTPc.c

WORD wUploadChunkOffset;

Description

This is variable wUploadChunkOffset.

10.20.3.23

wUploadChunkOffsetForRetransmit Variable

File

TFTPc.c

WORD wUploadChunkOffsetForRetransmit;

Description

This is variable wUploadChunkOffsetForRetransmit.

10.21

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 ( see page 609) 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 ( see page 608), TICK_MINUTE ( see page 608), and TICK_HOUR ( see page 608) can be used to

compare against logical time increments.

The following example implements a delay of 0.5 seconds using the Tick module:

TICK startTime;

// ...state machine and other states

case

SM_SET_DELAY:

startTime = TickGet();

sm = SM_DELAY_WAIT;

return

;

case

SM_DELAY_WAIT:

((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 ( see page 609), TickGetDiv256 ( see page 609),

606

10.21 Tick Module Microchip TCP/IP Stack Help Tick Public Members

and TickGetDiv64K ( see page 610) 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.

10.21.1

Tick Public Members

Functions

Name

TickConvertToMilliseconds

( see page 608)

TickGet ( see page 609)

TickGetDiv256 ( see page

609)

TickGetDiv64K ( see page

610)

Description

Converts a Tick value or difference to milliseconds.

Obtains the current Tick value.

Obtains the current Tick value divided by 256.

Obtains the current Tick value divided by 64K.

Macros

Module

TICK_HOUR ((QWORD)TICKS_PER_SECOND*3600ull)

Types

Name

TICK_HOUR ( see page

608)

TICK_MINUTE ( see page

608)

TICK_SECOND ( see page

608)

Description

Represents one hour in Ticks

Represents one minute in Ticks

Represents one second in Ticks

Name

TICK ( see page 607)

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.

Description

The following functions and variables are available to the stack application.

10.21.1.1

TICK Type

File

Tick.h

C typedef

DWORD TICK;

Description

607

10.21 Tick Module Microchip TCP/IP Stack Help Tick Public Members

10.21.1.2

TICK_HOUR Macro

File

Tick.h

#define

Description

Represents one hour in Ticks

10.21.1.3

TICK_MINUTE Macro

File

Tick.h

#define

TICK_MINUTE ((QWORD)TICKS_PER_SECOND*60ull)

Description

Represents one minute in Ticks

10.21.1.4

TICK_SECOND Macro

File

Tick.h

#define

TICK_SECOND ((QWORD)TICKS_PER_SECOND)

Description

Represents one second in Ticks

10.21.1.5

TickConvertToMilliseconds Function

File

Tick.h

DWORD TickConvertToMilliseconds(

DWORD dwTickValue

);

Returns

Input value expressed in milliseconds.

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.

Remarks

This function performs division on DWORDs, which is slow. Avoid using it unless you absolutely must (such as displaying

608

10.21 Tick Module Microchip TCP/IP Stack Help Tick Public Members

data to a user). For timeout comparisons, compare the current value to a multiple or fraction of TICK_SECOND ( see page

608), which will be calculated only once at compile time.

Preconditions

None

Parameters

dwTickValue

Description

Value to convert to milliseconds

10.21.1.6

TickGet Function

File

Tick.h

DWORD TickGet();

Returns

Lower 32 bits of the current Tick value.

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 ( see page 609) or TickGetDiv64K ( see page 610)

for longer periods of time.

Preconditions

None

10.21.1.7

TickGetDiv256 Function

File

Tick.h

DWORD TickGetDiv256();

Returns

Middle 32 bits of the current Tick value.

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 ( see page 609) for shorter periods or TickGetDiv64K ( see page 610)

for longer ones.

Preconditions

None

609

10.21 Tick Module Microchip TCP/IP Stack Help Tick Stack Functions

10.21.1.8

TickGetDiv64K Function

File

Tick.h

DWORD TickGetDiv64K();

Returns

Upper 32 bits of the current Tick value.

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 ( see page 609) or

TickGetDiv256 ( see page 609) for shorter periods of time.

Preconditions

None

10.21.2

Tick Stack Functions

Functions

Name

TickInit ( see page 610)

Description

Initializes the Tick manager module.

TickUpdate ( see page 611) Updates the tick value when an interrupt occurs.

Module

TICKS_PER_SECOND ( see page 612)

Description

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.

10.21.2.1

TickInit Function

File

Tick.h

C void

TickInit();

Returns

None

Description

Configures the Tick module and any necessary hardware resources.

Remarks

This function is called only one during lifetime of the application.

610

10.21 Tick Module

Preconditions

None

Microchip TCP/IP Stack Help

10.21.2.2

TickUpdate Function

File

Tick.h

C void

TickUpdate();

Returns

None

Description

Updates the tick value when an interrupt occurs.

Preconditions

None

Tick Internal Members

10.21.3

Tick Internal Members

Functions

Name

GetTickCopy ( see page

612)

Macros

Name

Module

dwInternalTicks ( see page

Description

Reads the tick value.

Description

Internal core clock drives timer with 1:256 prescaler #define

TICKS_PER_SECOND (32768ul) // 32kHz crystal drives timer with no scalar

Variables

Name

611)

vTickReading ( see page

612)

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.

6-byte value to store Ticks. Allows for use over longer periods of time.

Description

The following functions and variables are designated as internal to the Tick module.

10.21.3.1

dwInternalTicks Variable

File

Tick.c

611

10.22 UDP Microchip TCP/IP Stack Help

C volatile

DWORD dwInternalTicks = 0;

Description

10.21.3.2

GetTickCopy Function

File

Tick.c

C static void

GetTickCopy();

Returns

None

Description

This function performs an interrupt-safe and synchronized read of the 48-bit Tick value.

Preconditions

None

10.21.3.3

TICKS_PER_SECOND Macro

File

Tick.h

#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

10.21.3.4

vTickReading Variable

File

Tick.c

BYTE vTickReading[6];

Description

6-byte value to store Ticks. Allows for use over longer periods of time.

612

10.22 UDP Microchip TCP/IP Stack Help

10.22

UDP

Types

Name

UDP_STATE ( see page

633)

Description

UDP States

Description

UDP is a standard transport layer protocol described in RFC 768. It provides fast but unreliable data-gram based transfers over networks, and forms the foundation SNTP, SNMP, DNS, and many other protocol standards.

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 ( see page 157) are opened using UDPOpen ( see page 617). 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 ( see page 617).

Once the socket is opened, you can immediately begin transmitting data. To transmit a segment, call UDPIsPutReady ( see page 621) to determine how many bytes can be written and to designate a currently active socket. Then, use any of the

UDPPut ( see page 621) family of functions to write data to the socket. Once all data has been written, call UDPFlush ( see page 619) 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 ( see page 621) but before calling UDPFlush ( see page 619), the

data may be lost or the module may behave unpredictably.

613

10.22 UDP Microchip TCP/IP Stack Help UDP Public Members

To check for received segments, call UDPIsGetReady ( see page 620). If the return value is non-zero, your application

must consume the segment by reading data with the UDPGet ( see page 619) 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 ( see page 618) to release it back to the pool for future use.

10.22.1

UDP Public Members

Functions

Name

UDPOpenEx ( see page

616)

Description

Opens a UDP socket for a client.

UDPClose ( see page 618)

Closes a UDP socket and frees the handle.

UDPDiscard ( see page

618)

Discards any remaining RX data from a UDP socket.

UDPFlush ( see page 619)

Transmits all pending data in a UDP socket.

UDPGet ( see page 619)

Reads a byte from the currently active socket.

UDPGetArray ( see page

620)

Reads an array of bytes from the currently active socket.

UDPIsGetReady ( see page

620)

Determines how many bytes can be read from the UDP socket.

UDPIsPutReady ( see page

621)

UDPPut ( see page 621)

UDPPutArray ( see page

622)

Determines how many bytes can be written to the UDP socket.

Writes a byte to the currently active socket.

Writes an array of bytes to the currently active socket.

Writes an array of bytes from ROM to the currently active socket.

UDPPutROMArray ( see page 622)

UDPPutROMString ( see page 623)

UDPPutString ( see page

623)

Writes null-terminated string from ROM to the currently active socket.

Writes null-terminated string to the currently active socket.

UDPSetRxBuffer ( see page 624)

Moves the pointer within the RX buffer.

UDPSetTxBuffer ( see page

624)

Moves the pointer within the TX buffer.

UDPIsOpened ( see page

625)

Determines if a socket has an established connection.

Macros

Name

INVALID_UDP_SOCKET ( see page 615)

Description

INVALID_UDP_PORT ( see page 615)

Indicates a UDP port that is not valid

Indicates a UDP socket that is not valid

UDPOpen ( see page 617)

Macro of the legacy version of UDPOpen.

UDP_OPEN_IP_ADDRESS

( see page 625)

Create a client socket and use dwRemoteHost as a literal IP address.

UDP_OPEN_NODE_INFO

( see page 625)

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.

614

10.22 UDP Microchip TCP/IP Stack Help UDP Public Members

UDP_OPEN_RAM_HOST ( see page 626)

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 ( see page 626)

UDP_OPEN_SERVER ( see page 626)

Emit an undeclared identifier diagnostic if code tries to use

UDP_OPEN_ROM_HOST while the DNS client module is not enabled.

Create a server socket and ignore dwRemoteHost.

Module

UDP_SOCKET UDPOpenEx(

Types

Name

UDP_SOCKET ( see page

615)

Description

Provides a handle to a UDP Socket

Description

The following functions and variables are available to the stack application.

10.22.1.1

INVALID_UDP_PORT Macro

File

UDP.h

#define

INVALID_UDP_PORT (0ul)

// Indicates a UDP port that is not valid

Description

Indicates a UDP port that is not valid

10.22.1.2

INVALID_UDP_SOCKET Macro

File

UDP.h

#define

INVALID_UDP_SOCKET (0xffu)

// Indicates a UDP socket that is not valid

Description

Indicates a UDP socket that is not valid

10.22.1.3

UDP_SOCKET Type

File

UDP.h

C typedef

BYTE UDP_SOCKET;

Description

Provides a handle to a UDP Socket

615

10.22 UDP Microchip TCP/IP Stack Help UDP Public Members

10.22.1.4

UDPOpenEx Function

File

UDP.h

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 ( see page 174) 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 ( see page 191) 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 ( see page 180) only on the indicated port.

Sockets ( see page 157) are statically allocated on boot, but can be claimed with this function and freed using UDPClose

( see page 618) .

Remarks

When finished using the UDP socket handle, call the UDPClose ( see page 618)() function to free the socket and delete

the handle.

Preconditions

UDPInit ( see page 627) should be called.

Parameters

remoteHost

Description

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.

616

10.22 UDP remoteHostType

Microchip TCP/IP Stack Help UDP Public Members

Any one of the following flags to identify the meaning of the remoteHost parameter:

• UDP_OPEN_SERVER ( see page 626) = Open a server socket and

ignore the remoteHost parameter. (e.g. - SNMP agent, DHCP server,

Announce ( see page 160))

• UDP_OPEN_IP_ADDRESS ( see page 625) = Open a client socket and

connect ( see page 176) 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 ( see page 625) = Open a client socket and

connect ( see page 176) it to a remote IP and MAC addresses pair stored

in a NODE_INFO structure.

• UDP_OPEN_RAM_HOST ( see page 626) = Open a client socket and

connect ( see page 176) 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 ( see page 626) = Open a client socket and

connect ( see page 176) 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"

UDP port number to listen ( see page 180) on. If 0, stack will dynamically

assign a unique port number to use.

For client sockets, the remote port number.

localPort remotePort

Return Values

Success

Failure

Description

A UDP socket handle that can be used for subsequent UDP API calls.

INVALID_UDP_SOCKET ( see page 615). This function fails when no more

UDP socket handles are available. Increase MAX_UDP_SOCKETS to make more sockets available.

10.22.1.5

UDPOpen Macro

File

UDP.h

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

Remarks

When finished using the UDP socket handle, call the UDPClose ( see page 618)() function to free the socket and delete

the handle.

Preconditions

UDPInit ( see page 627)() must have been previously called.

Parameters

localPort

Description

UDP port number to listen ( see page 180) on. If 0, stack will dynamically

assign a unique port number to use.

617

10.22 UDP remoteNode

Microchip TCP/IP Stack Help UDP Public Members

For client sockets, the remote port number.

remotePort

Return Values

Success

Failure

Description

A UDP socket handle that can be used for subsequent UDP API calls.

INVALID_UDP_SOCKET ( see page 615). This function fails when no more

UDP socket handles are available. Increase MAX_UDP_SOCKETS to make more sockets available.

10.22.1.6

UDPClose Function

File

UDP.h

C void

UDPClose(

UDP_SOCKET s

);

Returns

None

Description

UDP_SOCKET (

see page 615) UDPOpen (

see page 617)(UDP_PORT ( see page 631) localPort, NODE_INFO

*remoteNode, UDP_PORT ( see page 631) 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.

Remarks

This function does not affect the previously designated active socket.

Preconditions

UDPInit ( see page 627)() must have been previously called.

Parameters

Description

The socket handle to be released. If an illegal handle value is provided, the function safely does nothing.

10.22.1.7

UDPDiscard Function

File

UDP.h

C void

UDPDiscard();

Returns

None

Description

This function discards any remaining received data in the currently active UDP socket.

618

10.22 UDP Microchip TCP/IP Stack Help

Remarks

It is safe to call this function more than is necessary. If no data is available, this function does nothing.

Preconditions

UDPIsGetReady ( see page 620)() was previously called to select the currently active socket.

UDP Public Members

10.22.1.8

UDPFlush Function

File

UDP.h

C void

UDPFlush();

Returns

None

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.

Remarks

Note that unlike TCPFlush ( see page 542), UDPFlush must be called before returning to the main stack loop. There is no

auto transmit for UDP segments.

Preconditions

UDPIsPutReady ( see page 621)() was previously called to specify the current socket, and data has been written to the socket using the UDPPut ( see page 621) family of functions.

10.22.1.9

UDPGet Function

File

UDP.h

BOOL UDPGet(

BYTE * v

);

Description

This function reads a single byte from the currently active UDP socket, while decrementing the remaining buffer length.

UDPIsGetReady ( see page 620) should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsGetReady ( see page 620)() was previously called to specify the current socket.

Parameters

Description

The buffer to receive the data being read.

Parameters

Return Values

TRUE

Description

A byte was successfully read

619

10.22 UDP

FALSE

Microchip TCP/IP Stack Help

No data remained in the read buffer

UDP Public Members

10.22.1.10

UDPGetArray Function

File

UDP.h

WORD UDPGetArray(

BYTE * cData,

WORD wDataLen

);

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.

Description

This function reads an array of bytes from the currently active UDP socket, while decrementing the remaining bytes

available. UDPIsGetReady ( see page 620) should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsGetReady ( see page 620)() was previously called to specify the current socket.

Parameters

cData wDateLen

Description

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 ( see page 624)() will be more efficient).

Number of bytes to be read from the socket.

10.22.1.11

UDPIsGetReady Function

File

UDP.h

WORD UDPIsGetReady(

UDP_SOCKET s

);

Returns

The number of bytes that can be read from this socket.

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 ( see page 627)() must have been previously called.

Parameters

Description

The socket to be made active (which has already been opened or is listening)

620

10.22 UDP Microchip TCP/IP Stack Help UDP Public Members

10.22.1.12

UDPIsPutReady Function

File

UDP.h

WORD UDPIsPutReady(

UDP_SOCKET s

);

Returns

The number of bytes that can be written to this socket.

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 ( see page 627)() must have been previously called.

Parameters

Description

The socket to be made active

10.22.1.13

UDPPut Function

File

UDP.h

BOOL UDPPut(

BYTE v

);

Description

This function writes a single byte to the currently active UDP socket, while incrementing the buffer length. UDPIsPutReady

( see page 621) should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsPutReady ( see page 621)() was previously called to specify the current socket.

Parameters

Description

The byte to be loaded into the transmit buffer.

Parameters

Return Values

TRUE

FALSE

Description

The byte was successfully written to the socket.

The transmit buffer is already full and so the write failed.

621

10.22 UDP Microchip TCP/IP Stack Help UDP Public Members

10.22.1.14

UDPPutArray Function

File

UDP.h

WORD UDPPutArray(

BYTE * cData,

WORD wDataLen

);

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.

Description

This function writes an array of bytes to the currently active UDP socket, while incrementing the buffer length.

UDPIsPutReady ( see page 621) should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsPutReady ( see page 621)() was previously called to specify the current socket.

Parameters

cData wDateLen

Description

The array to write to the socket.

Number of bytes from cData to be written.

10.22.1.15

UDPPutROMArray Function

File

UDP.h

WORD UDPPutROMArray(

ROM BYTE * cData,

WORD wDataLen

);

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.

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 ( see page 621) should be used before calling this function to specify the currently active socket.

Remarks

This function is aliased to UDPPutArray ( see page 622) on non-PIC18 platforms.

Preconditions

UDPIsPutReady ( see page 621)() was previously called to specify the current socket.

622

10.22 UDP

Parameters

cData wDateLen

Microchip TCP/IP Stack Help

Description

The array to write to the socket.

Number of bytes from cData to be written.

UDP Public Members

10.22.1.16

UDPPutROMString Function

File

UDP.h

ROM BYTE* UDPPutROMString(

ROM BYTE * strData

);

Returns

A pointer to the byte following the last byte written. Note that this is different than the UDPPutArray ( see page 622)

functions. If this pointer does not dereference to a NULL byte, then the buffer became full and the input data was truncated.

Description

This function writes a null-terminated string from ROM to the currently active UDP socket, while incrementing the buffer

length. UDPIsPutReady ( see page 621) should be used before calling this function to specify the currently active socket.

Remarks

This function is aliased to UDPPutString ( see page 623) on non-PIC18 platforms.

Preconditions

UDPIsPutReady ( see page 621)() was previously called to specify the current socket.

Parameters

cData

Description

Pointer to the string to be written to the socket.

10.22.1.17

UDPPutString Function

File

UDP.h

BYTE* UDPPutString(

BYTE * strData

);

Returns

A pointer to the byte following the last byte written. Note that this is different than the UDPPutArray ( see page 622)

functions. If this pointer does not dereference to a NULL byte, then the buffer became full and the input data was truncated.

Description

This function writes a null-terminated string to the currently active UDP socket, while incrementing the buffer length.

UDPIsPutReady ( see page 621) should be used before calling this function to specify the currently active socket.

Preconditions

UDPIsPutReady ( see page 621)() was previously called to specify the current socket.

623

10.22 UDP

Parameters

cData

Microchip TCP/IP Stack Help

Description

Pointer to the string to be written to the socket.

UDP Public Members

10.22.1.18

UDPSetRxBuffer Function

File

UDP.h

C void

UDPSetRxBuffer(

WORD wOffset

);

Returns

None

Description

This function allows the read location within the RX buffer to be specified. Future calls to UDPGet ( see page 619) and

UDPGetArray ( see page 620) will read data from the indicated location forward.

Preconditions

UDPInit ( see page 627)() must have been previously called and a socket is currently active.

Parameters

wOffset

Description

Offset from beginning of UDP packet data payload to place the read pointer.

10.22.1.19

UDPSetTxBuffer Function

File

UDP.h

C void

UDPSetTxBuffer(

WORD wOffset

);

Returns

None

Description

This function allows the write location within the TX buffer to be specified. Future calls to UDPPut ( see page 621),

UDPPutArray ( see page 622), UDPPutString ( see page 623), etc will write data from the indicated location.

Preconditions

UDPInit ( see page 627)() must have been previously called and a socket is currently active.

Parameters

wOffset

Description

Offset from beginning of UDP packet data payload to place the write pointer.

624

10.22 UDP Microchip TCP/IP Stack Help UDP Public Members

10.22.1.20

UDPIsOpened Function

File

UDP.h

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 ( see page 617) to determine when the connection is set up and ready for use.

Remarks

None

Preconditions

UDP is initialized.

Parameters

socket ( see page 185)

Return Values

TRUE

FALSE

Description

The socket to check.

Description

The socket has been opened and ARP has been resolved.

The socket is not currently connected.

10.22.1.21

UDP_OPEN_IP_ADDRESS Macro

File

UDP.h

#define

UDP_OPEN_IP_ADDRESS 3u

Description

Create a client socket and use dwRemoteHost as a literal IP address.

10.22.1.22

UDP_OPEN_NODE_INFO Macro

File

UDP.h

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

625

10.22 UDP Microchip TCP/IP Stack Help UDP Stack Members

10.22.1.23

UDP_OPEN_RAM_HOST Macro

File

UDP.h

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

10.22.1.24

UDP_OPEN_ROM_HOST Macro

File

UDP.h

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

10.22.1.25

UDP_OPEN_SERVER Macro

File

UDP.h

#define

UDP_OPEN_SERVER 0u

Description

Create a server socket and ignore dwRemoteHost.

10.22.2

UDP Stack Members

Functions

Name

UDPInit ( see page 627)

Description

Initializes the UDP module.

UDPProcess ( see page

627)

Handles an incoming UDP segment.

UDPTask ( see page 628)

Performs state management and housekeeping for UDP.

Module

UDPInit ( see page 627)() has been called an a UDP segment is ready in the MAC buffer.

Description

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.

626

10.22 UDP Microchip TCP/IP Stack Help UDP Stack Members

10.22.2.1

UDPInit Function

File

UDP.h

C void

UDPInit();

Returns

None

Description

Initializes the UDP module. This function initializes all the UDP sockets to the closed state.

Remarks

This function is called only one during lifetime of the application.

Preconditions

None

Section

Function Prototypes

10.22.2.2

UDPProcess Function

File

UDP.h

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

Parameters

remoteNode localIP len

Return Values

TRUE

FALSE

Description

The remote node that sent this segment.

The destination IP address for this segment.

Total length of the UDP segment.

Description

A valid packet is waiting and the stack applications should be called to handle it.

The packet was discarded.

627

10.22 UDP Microchip TCP/IP Stack Help UDP Internal Members

10.22.2.3

UDPTask Function

File

UDP.h

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

Remarks

UDPTask() is called once per StackTask() iteration to ensure that calls to UDPIsPutReady ( see page 621)() always update

the Ethernet Write pointer location between StackTask() iterations.

Preconditions

None

10.22.3

UDP Internal Members

Functions

Name

FindMatchingSocket ( see page 629)

Description

Matches an incoming UDP segment to a currently active socket.

Macros

Name

LOCAL_UDP_PORT_END_NUMBER

( see page 630)

Description

Last port number for randomized local port number selection

LOCAL_UDP_PORT_START_NUMBER

( see page 630)

First port number for randomized local port number selection

Module

UDP_SOCKET_INFO ( see page 631)

Structures

Name

UDP_HEADER ( see page

631)

Description

Stores the header of a UDP packet

Stores information about a current UDP socket

Types

Name

UDP_PORT ( see page

631)

Description

Stores a UDP Port Number

Variables

Name

activeUDPSocket ( see page 629)

Description

Indicates which UDP socket is currently active

628

10.22 UDP Microchip TCP/IP Stack Help UDP Internal Members

LastPutSocket ( see page

630)

SocketWithRxData ( see page 630)

UDPRxCount ( see page

632)

UDPSocketInfo ( see page

632)

Indicates the last socket to which data was written

Indicates which socket has currently received data for this loop

Number of bytes read from this UDP segment

Stores an array of information pertaining to each UDP socket

UDPTxCount ( see page

632)

Number of bytes written to this UDP segment

wGetOffset ( see page 632) Offset from beginning of payload from where data is to be read.

wPutOffset ( see page 633)

Offset from beginning of payload where data is to be written.

Description

The following functions and variables are designated as internal to the UDP module.

10.22.3.1

activeUDPSocket Variable

File

UDP.c

UDP_SOCKET activeUDPSocket;

Description

Indicates which UDP socket is currently active

10.22.3.2

FindMatchingSocket Function

File

UDP.c

C static

UDP_SOCKET FindMatchingSocket(

UDP_HEADER * h,

NODE_INFO * remoteNode,

IP_ADDR * localIP

);

Returns

A UDP_SOCKET ( see page 615) handle of a matching socket, or INVALID_UDP_SOCKET ( see page 615) when no

match could be made.

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

h remoteNode localIP

Description

The UDP header that was received.

IP and MAC of the remote node that sent this segment.

IP address that this segment was destined for.

629

10.22 UDP

Section

Function Prototypes

Microchip TCP/IP Stack Help

10.22.3.3

LastPutSocket Variable

File

UDP.c

UDP_SOCKET LastPutSocket = INVALID_UDP_SOCKET;

Description

Indicates the last socket to which data was written

10.22.3.4

LOCAL_UDP_PORT_END_NUMBER Macro

File

UDP.c

#define

LOCAL_UDP_PORT_END_NUMBER (8192u)

Description

Last port number for randomized local port number selection

10.22.3.5

LOCAL_UDP_PORT_START_NUMBER Macro

File

UDP.c

#define

LOCAL_UDP_PORT_START_NUMBER (4096u)

Description

First port number for randomized local port number selection

10.22.3.6

SocketWithRxData Variable

File

UDP.c

UDP_SOCKET SocketWithRxData = INVALID_UDP_SOCKET;

Description

Indicates which socket has currently received data for this loop

UDP Internal Members

630

10.22 UDP Microchip TCP/IP Stack Help

10.22.3.7

UDP_HEADER Structure

File

UDP.h

C typedef struct

{

UDP_PORT SourcePort;

UDP_PORT DestinationPort;

WORD Length;

WORD Checksum;

} UDP_HEADER;

Members

UDP_PORT SourcePort;

UDP_PORT DestinationPort;

WORD Length;

WORD Checksum;

Description

Stores the header of a UDP packet

Description

Source UDP port

Destination UDP port

Length of data

UDP checksum of the data

10.22.3.8

UDP_PORT Type

File

UDP.h

C typedef

WORD UDP_PORT;

Description

Stores a UDP Port Number

10.22.3.9

UDP_SOCKET_INFO Structure

File

UDP.h

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;

UDP Internal Members

631

10.22 UDP Microchip TCP/IP Stack Help UDP Internal Members

Members

NODE_INFO remoteNode;

DWORD remoteHost;

UDP_PORT remotePort;

UDP_PORT localPort;

UDP_STATE smState; unsigned char bRemoteHostIsROM : 1;

Description

10 bytes for MAC and IP address

RAM or ROM pointer to a hostname string (ex: "www.microchip.com")

Remote node's UDP port number

Local UDP port number, or INVALID_UDP_PORT ( see page 615) when free

State of this socket

Remote host is stored in ROM

Description

Stores information about a current UDP socket

10.22.3.10

UDPRxCount Variable

File

UDP.c

WORD UDPRxCount;

Description

Number of bytes read from this UDP segment

10.22.3.11

UDPSocketInfo Variable

File

UDP.c

UDP_SOCKET_INFO UDPSocketInfo[MAX_UDP_SOCKETS];

Description

Stores an array of information pertaining to each UDP socket

10.22.3.12

UDPTxCount Variable

File

UDP.c

WORD UDPTxCount;

Description

Number of bytes written to this UDP segment

10.22.3.13

wGetOffset Variable

File

UDP.c

632

10.22 UDP Microchip TCP/IP Stack Help

WORD wGetOffset;

Description

Offset from beginning of payload from where data is to be read.

10.22.3.14

wPutOffset Variable

File

UDP.c

WORD wPutOffset;

Description

Offset from beginning of payload where data is to be written.

10.22.4

Types

Enumerations

Name

UDP_STATE ( see page

633)

Module

Wi-Fi Connection Profile ( see page 637) Functions to setup, use, and teardown connection profiles

Description

UDP States

10.22.4.1

UDP_STATE Enumeration

File

UDP.h

C typedef enum

{

UDP_DNS_IS_RESOLVED,

UDP_DNS_RESOLVE,

UDP_GATEWAY_SEND_ARP,

UDP_GATEWAY_GET_ARP,

UDP_CLOSED,

UDP_OPENED

} UDP_STATE;

Members

UDP_DNS_IS_RESOLVED

UDP_DNS_RESOLVE

UDP_GATEWAY_SEND_ARP

UDP_GATEWAY_GET_ARP

UDP_CLOSED

Description

UDP States

Description

Special state for UDP client mode sockets

Socket is idle and unallocated

Types

633

Microchip TCP/IP Stack Help 11

Wi-Fi API

Modules

Name Description

Wi-Fi Connection Algorithm ( see page

652)

Functions to alter the behavior of the connection process

Functions to manage the connection process

Wi-Fi Connection Manager ( see page

676)

Wi-Fi Scan ( see page 679)

Functions to direct the MRF24WB0M / MRF24WG0M to initiate a site survey

Wi-Fi Tx Power Control ( see page 692)

API to control the transmit (Tx) power of the MRF24WB0M / MRF24WG0M

Wi-Fi Miscellaneous ( see page 705)

Functions to alter the power savings features of the MRF24WB0M /

MRF24WG0M

Functions for controlling miscellaneous features of the MRF24WB0M /

MRF24WG0M

Description

Feature similarities and differences of MRF24WB0M and MRF24WG0M

MRF24WB0M MRF24WG0M

1 , 2 Mbps

Ad-hoc (OPEN, WEP)

802.11b and 802.11g rates

Ad-hoc (OPEN, WEP)

Infrastructure (OPEN, WEP,

WPA/WPA2)

Infrastructure (OPEN, WEP, WPA/WPA2, WPS)

SoftAP (OPEN, WEP)

Wi-Fi Direct (WPS)

WPA2-Enterprise Security Modes (EAP-PEAP/MSCHAPv2 and EAP-TTLS/MSCHAPv)

Unlike Ethernet, a Wi-Fi 802.11 application needs to initiate a connection to an access point, Wi-Fi Direct or an ad hoc network, before data communications can commence.

The WF_Config.h file has several compile-time constants that can be customized (e.g. MY_DEFAULT_SSID_NAME) as needed.

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 ( see page 639)()). 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, WPA2, WPS-PBC, WPS-PIN, etc.) c. Network type (infrastructure, ad hoc, softAP, Wi-Fi Direct).

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…

634

11 Microchip TCP/IP Stack Help

3) Once a connection profile and the connection algorithm are customized for an application, the WF_CMConnect ( see page 677)() function must be called to initiate the connection process.

4) After WF_Connect() is called the host application will be notified when the MRF24WB0M / MRF24WG0M has succeeded

(or failed) in establishing a connection via the event mechanism. The WF_Config.c file has a function, WF_ProcessEvent ( see page 717)(), that is a template for processing MRF24WB0M / MRF24WG0M 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 ( see page 717)() when the connection succeeded. Please refer to WF_ProcessEvent ( see page 717) for more information on WiFi event handling.

The MRF2WB0M / MRF24WG0M 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.

Wi-Fi DIRECT (CFG_WF_P2P)

To start up as a Wi-Fi direct group client device, define

• MY_DEFAULT_SSID_NAME as "DIRECT-" which is an unique specifier to identify a Wi-Fi Direct network.

• MY_DEFAULT_CHANNEL LIST as {1, 6, 11} which are specified social channels for Wi-Fi Direct network.

Below describes the host API to the MRF24WB0M / MRF24WG0M on-chip connection manager which creates and maintains Wi-Fi connections. The API is divided into these major sections:

API Section Description

Initialization ( see page

143)

Functions to initialize the host API and MRF24WB0M / MRF24WG0M

Connection Profile

Connection Algorithm

Connection Manager

Scan

Tx Power Control

Power Save

Multicast

Miscellaneous

MRF24WB0M

MRF24WG0M Events

Functions to create and maintain one or more connection profiles

Functions to fine tune the connection algorithm

Functions to start and stop an 802.11 connection

Functions to scan for wireless networks

Functions to control the MRF24WB0M / MRF24WG0M Tx power

Functions to save power consumption by the MRF24WB0M / MRF24WG0M

Functions to create multicast filters

Functions to set a custom MAC address, get device information, etc.

Functions to handle events from the MRF24WB0M / MRF24WG0M

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 / MRF24WG0M. To communicate with the MRF24WB0M / MRF24WG0M, 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

635

11 Microchip TCP/IP Stack Help

• 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

WF_SpiInit()

WF_SpiTxRx()

WF_SpiEnableChipSelect()

Description

Initializes the host CPU SPI controller for usage by the Wi-Fi driver. Called by the

Wi-Fi driver during initialization.

Transmits and/or receives SPI data from the MRF24WB0M / MRF24WG0M.

Set slave select line on MRF24WB0M / MRF24WG0M 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 / MRF24WG0M SPI context.

WF_SpiDisableChipSelect() Set slave select line on MRF24WB0M / MRF24WG0M 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 /

MRF24WG0M 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 / MRF24WG0M 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

WF_EintInit()

WF_EintEnable()

WF_EintDisable()

WF_EintIsr()

WF_EintIsDisabled()

WFEintHandler()

Description

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.

Enables the MRF24WB0M / MRF24WG0M external interrupt. If using real interrupts then enable the interrupt. If polling the EXINT pin then this function enables polling of the pin.

Disables the MRF24WB0M / MRF24WG0M external interrupt. If using real interrupts then disable the interrupt. If polling the EXINT pin then this function disables polling of the pin.

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.

Returns true if the external interrupt is disabled, else returns false.

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 /

MRF24WG0M interrupt service routine (ISR) occurs.

636

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help

WF_Config.c/h

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

WF_USE_SCAN_FUNCTIONS

WF_USE_TX_POWER_CONTROL_FUNCTIONS

WF_USE_POWER_SAVE_FUNCTIONS

WF_USE_MULTICAST_FUNCTIONS

WF_USE_INDIVIDUAL_SET_GETS

WF_USE_GROUP_SET_GETS

Controlling Functions

Scan API

Tx power control API

Power save API

Multicast API

Affects all get and set functions, except the following:

WF_CPSetElements ( see page 646)()

WF_CPGetElements ( see page 641)()

WF_CASetElements ( see page 665)()

WF_CAGetElements ( see page 657)()

Affects the following functions:

WF_CPSetElements ( see page 646)()

WF_CPGetElements ( see page 641)()

WF_CASetElements ( see page 665)()

WF_CAGetElements ( see page 657)()

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 ( see page 717)()

can be customized to support desired handling of events.

11.1

Wi-Fi Connection Profile

Module

RAW_MGMT_RX_ID ( see page 652)

637

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help Connection Profile Public Members

Macros

Name

Description

This is macro RAW_MGMT_RX_ID.

Description

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 / MRF24WG0M 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 ( see page 678)()

, update the connection profile, then call

WF_CMConnect ( see page

677)()

11.1.1

Connection Profile Public Members

Functions

Name

WF_CPCreate ( see page

639)

WF_CPDelete ( see page

640)

WF_CPGetAdHocBehavior

( see page 640)

WF_CPGetBssid ( see page 641)

WF_CPGetElements ( see page 641)

WF_CPGetIds ( see page

642)

WF_CPGetNetworkType ( see page 642)

WF_CPGetSecurity ( see page 643)

WF_CPGetSsid ( see page

644)

WF_CPSetAdHocBehavior

( see page 644)

WF_CPSetBssid ( see page 645)

WF_CPSetElements ( see page 646)

WF_CPSetNetworkType ( see page 646)

Description

Creates a Connection Profile on the MRF24W.

Deletes a Connection Profile on the MRF24W.

Gets the desired Ad Hoc behavior

Gets the BSSID for the specified Connection Profile ID.

Reads the Connection Profile elements for the specified ID.

Retrieves the CP ID bit mask.

Gets the network type for the specified Connection Profile ID.

Gets the security for the specified Connection Profile.

Gets the SSID for the specified Connection Profile ID.

Selects the desired Ad Hoc behavior

Sets the BSSID for the specified Connection Profile ID.

Writes out data for a specific connection profile element.

Sets the network type for the specified Connection Profile ID.

638

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help Connection Profile Public Members

WF_CPSetSecurity ( see page 647)

WF_CPSetSsid ( see page

648)

WF_CPGetSsidType ( see page 649)

WF_CPSetSsidType ( see page 650)

Sets the security for the specified Connection Profile.

Sets the SSID for the specified Connection Profile ID.

Gets the SSID type for the specified Connection Profile ID.

Sets the SSID type for the specified Connection Profile ID.

Module

Wi-Fi Connection Profile ( see page 637)

Structures

Name

WFCPElementsStruct ( see page 648)

Description

Connection profile elements structure

Description

11.1.1.1

WF_CPCreate Function

File

WFApi.h

C void

WF_CPCreate(

UINT8 * p_CpId

);

Returns

None.

Description

Connection Profile Functions

Requests the MRF24W 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 MRF24W. Users are encouraged to use 1 profile ID for MRF24W based on v5 stack SW. In v6 stack SW, plan is to have

1 profile ID for MRF24W but stack will be designed to have capability to handle multiple profiles.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_CpId

Description

Pointer to where Connection Profile ID will be written. If function fails, the CP ID will be set to 0xff.

639

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help Connection Profile Public Members

11.1.1.2

WF_CPDelete Function

File

WFApi.h

C void

WF_CPDelete(

UINT8 CpId

);

Returns

None.

Description

Deletes the specified Connection Profile. If the Connection Profile was in FLASH it will be erased from FLASH.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId

Description

Connection Profile to delete.

11.1.1.3

WF_CPGetAdHocBehavior Function

File

WFApi.h

C void

WF_CPGetAdHocBehavior(

UINT8 CpId,

UINT8 * p_adHocBehavior

);

Returns

None.

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

Remarks

None.

Preconditions

MACInit must be called first.

640

11.1 Wi-Fi Connection Profile

Parameters

CpId adHocBehavior

Microchip TCP/IP Stack Help Connection Profile Public Members

Description

Connection Profile ID

Pointer to location of the adhoc behavior value for this connection profile.

11.1.1.4

WF_CPGetBssid Function

File

WFApi.h

C void

WF_CPGetBssid(

UINT8 CpId,

UINT8 * p_bssid

);

Returns

None.

Description

Gets the BSSID element in a Connection Profile.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId p_bssid

Description

Connection Profile ID

Pointer to the BSSID

11.1.1.5

WF_CPGetElements Function

File

WFApi.h

C void

WF_CPGetElements(

UINT8 CpId,

tWFCPElements * p_elements

);

Returns

None.

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.

Remarks

None.

641

11.1 Wi-Fi Connection Profile

Preconditions

MACInit must be called first.

Parameters

CpId p_elements

Microchip TCP/IP Stack Help Connection Profile Public Members

Description

Connectino Profile ID.

Pointer to Connection Profile elements structure.

11.1.1.6

WF_CPGetIds Function

File

WFApi.h

C void

WF_CPGetIds(

UINT8 * cpIdList

);

Returns

None.

Description

Returns a list of all Connection Profile IDs that have been created on the MRF24W. 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. Users are encouraged to use 1 profile ID for MRF24W based on v5 stack SW. In v6 stack SW, plan is to have 1 profile ID for MRF24W but stack will be designed to have capability to handle multiple profiles.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_cpIdList

Description

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.

11.1.1.7

WF_CPGetNetworkType Function

File

WFApi.h

C void

WF_CPGetNetworkType(

UINT8 CpId,

UINT8 * p_networkType

);

Returns

None.

642

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help Connection Profile Public Members

Description

Gets the Network Type element of the Connection Profile. Allowable values are:

• WF_INFRASTRUCTURE

• WF_ADHOC

• WF_P2P

• WF_SOFT_AP

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId networkType

Description

Connection Profile ID

Type of network to create (infrastructure or adhoc or p2p or softAP)

11.1.1.8

WF_CPGetSecurity Function

File

WFApi.h

C void

WF_CPGetSecurity(

UINT8 CpId,

UINT8 * p_securityType,

UINT8 * p_wepKeyIndex,

UINT8 * p_securityKey,

UINT8 * p_securityKeyLength

);

Returns

None.

Description

Configures security for a Connection Profile.

Security

WF_SECURITY_OPEN

WF_SECURITY_WEP_40

WF_SECURITY_WEP_104

WF_SECURITY_WPA_WITH_KEY

WF_SECURITY_WPA_WITH_PASS_PHRASE

WF_SECURITY_WPA2_WITH_KEY

WF_SECURITY_WPA2_WITH_PASS_PHRASE

WF_SECURITY_WPA_AUTO_WITH_KEY

WF_SECURITY_WPA_AUTO_WITH_PASS_PHRASE

WF_SECURITY_WPS_PUSH_BUTTON

WF_SECURITY_WPS_PIN

Key

N/A hex hex hex ascii hex ascii hex ascii

Length

N/A

4, 5 byte keys

4, 13 byte keys

32 bytes

8-63 ascii characters

32 bytes

8-63 ascii characters

32 bytes

8-63 ascii characters

643

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help Connection Profile Public Members

WF_SECURITY_WPA2_ENTERPRISE

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId securityType wepKeyIndex p_securityKey securityKeyLength

Description

Connection Profile ID

Value corresponding to the security type desired.

Only index 0 is valid. (Applicable for WF_SECURITY_WEP_40 or

WF_SECURITY_WEP_104)

Binary key or passphrase (not used if security is WF_SECURITY_OPEN)

Number of bytes in p_securityKey (not used if security is

WF_SECURITY_OPEN)

11.1.1.9

WF_CPGetSsid Function

File

WFApi.h

C void

WF_CPGetSsid(

UINT8 CpId,

UINT8 * p_ssid,

UINT8 * p_ssidLength

);

Returns

None.

Description

Gets the SSID and SSID Length elements in the Connection Profile.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId p_ssid ssidLength

Description

Connection Profile ID

Pointer to the SSID string

Pumber of bytes in the SSID

11.1.1.10

WF_CPSetAdHocBehavior Function

File

WFApi.h

644

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help Connection Profile Public Members

C void

WF_CPSetAdHocBehavior(

UINT8 CpId,

UINT8 adHocBehavior

);

Returns

None.

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

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId adHocBehavior

Description

Connection Profile ID

Value of the adhoc behavior for this connection profile.

11.1.1.11

WF_CPSetBssid Function

File

WFApi.h

C void

WF_CPSetBssid(

UINT8 CpId,

UINT8 * p_bssid

);

Returns

None.

Description

Sets the BSSID element in a Connection Profile.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId p_bssid

Description

Connection Profile ID

Pointer to the BSSID

645

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help Connection Profile Public Members

11.1.1.12

WF_CPSetElements Function

File

WFApi.h

C void

WF_CPSetElements(

UINT8 CpId,

tWFCPElements * p_elements

);

Returns

None.

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.

Remarks

None.

Preconditions

MACInit must be called.

Parameters

CpId p_elements

Description

Connectino Profile ID.

Pointer to Connection Profile elements structure.

11.1.1.13

WF_CPSetNetworkType Function

File

WFApi.h

C void

WF_CPSetNetworkType(

UINT8 CpId,

UINT8 networkType

);

Returns

None.

Description

Sets the Network Type element for the Connection Profile. Allowable values are:

• WF_INFRASTRUCTURE

• WF_ADHOC

• WF_P2P

• WF_SOFT_AP

Remarks

None.

646

11.1 Wi-Fi Connection Profile

Preconditions

MACInit must be called first.

Parameters

CpId networkType

Microchip TCP/IP Stack Help Connection Profile Public Members

Description

Connection Profile ID

Type of network to create (infrastructure or adhoc or p2p or softAP)

11.1.1.14

WF_CPSetSecurity Function

File

WFApi.h

C void

WF_CPSetSecurity(

UINT8 CpId,

UINT8 securityType,

UINT8 wepKeyIndex,

UINT8 * p_securityKey,

UINT8 securityKeyLength

);

Returns

None.

Description

Configures security for a Connection Profile.

Security

WF_SECURITY_OPEN

WF_SECURITY_WEP_40

WF_SECURITY_WEP_104

WF_SECURITY_WPA_WITH_KEY

WF_SECURITY_WPA_WITH_PASS_PHRASE

WF_SECURITY_WPA2_WITH_KEY

WF_SECURITY_WPA2_WITH_PASS_PHRASE

WF_SECURITY_WPA_AUTO_WITH_KEY

WF_SECURITY_WPA_AUTO_WITH_PASS_PHRASE

WF_SECURITY_WPS_PUSH_BUTTON

WF_SECURITY_WPS_PIN

WF_SECURITY_WPA2_ENTERPRISE

Remarks

None.

Preconditions

MACInit must be called first.

Key

N/A hex hex hex ascii hex ascii hex ascii

Length

N/A

4, 5 byte keys

4, 13 byte keys

32 bytes

8-63 ascii characters

32 bytes

8-63 ascii characters

32 bytes

8-63 ascii characters

647

11.1 Wi-Fi Connection Profile

Parameters

CpId securityType wepKeyIndex p_securityKey securityKeyLength

Microchip TCP/IP Stack Help Connection Profile Public Members

Description

Connection Profile ID

Value corresponding to the security type desired.

Only index 0 is valid. (Applicable for WF_SECURITY_WEP_40 or

WF_SECURITY_WEP_104)

Binary key or passphrase (not used if security is WF_SECURITY_OPEN)

Number of bytes in p_securityKey (not used if security is

WF_SECURITY_OPEN)

11.1.1.15

WF_CPSetSsid Function

File

WFApi.h

C void

WF_CPSetSsid(

UINT8 CpId,

UINT8 * p_ssid,

UINT8 ssidLength

);

Returns

None.

Description

Sets the SSID and SSID Length elements in the Connection Profile. Note that an Access Point can have either a visible or hidden SSID. If an Access Point uses a hidden SSID then an active scan must be used (see scanType field in the

Connection Algorithm).

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId p_ssid ssidLength

Description

Connection Profile ID

Pointer to the SSID string

Number of bytes in the SSID

11.1.1.16

WFCPElementsStruct Structure

File

WFApi.h

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;

648

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help Connection Profile Public Members

UINT8 wepDefaultKeyId;

UINT8 networkType;

UINT8 adHocBehavior;

UINT8 hiddenSSID;

UINT8 wepKeyType;

};

Members

UINT8 ssid[WF_MAX_SSID_LENGTH];

UINT8 bssid[WF_BSSID_LENGTH];

UINT8 ssidLength;

Description

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 MRF24W, when using this profile to connect ( see page 176), will scan all channels within its regional domain.

Default: SSID not used.

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)

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;

UINT8 wepDefaultKeyId;

Number of bytes used in the securityKey. Set to 0 if securityType is

WF_SECURITY_OPEN.

This field is only used if securityType is WF_SECURITY_WEP_40 or

WF_SECURITY_WEP_104. This field designates which of the four

WEP keys defined in securityKey to use when connecting to a WiFi network. Only WEP key index (wepDefaultKeyId) 0 is used in RF module FW.

UINT8 networkType;

UINT8 adHocBehavior;

UINT8 hiddenSSID;

UINT8 wepKeyType;

WF_INFRASTRUCTURE / WF_ADHOC / WF_P2P / WF_SOFT_AP

Default: WF_INFRASTRUCTURE

Only applicable if networkType is WF_ADHOC. Configures Adhoc behavior. Choices are:

1 - enable hidden ssid in adhoc mode

0- shared key, 1 - open key

Description

Connection profile elements structure

11.1.1.17

WF_CPGetSsidType Function

File

WFApi.h

C void

WF_CPGetSsidType(

UINT8 CpId,

UINT8 * hidden

);

Returns

None.

649

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help

Description

Gets the SSID type element in the Connection Profile.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId hidden

Description

Connection Profile ID

Pointer to the SSID type

Connection Profile Internal Members

11.1.1.18

WF_CPSetSsidType Function

File

WFApi.h

C void

WF_CPSetSsidType(

UINT8 CpId,

UINT8 hidden

);

Returns

None.

Description

Sets the SSID type element in the Connection Profile. This is valid only when we create AdHoc network.

Remarks

None.

Preconditions

MACInit must be called first.

11.1.2

Connection Profile Internal Members

Functions

Name

LowLevel_CPGetElement ( see page 651)

LowLevel_CPSetElement ( see page 651)

Description

Get an element of the connection profile on the MRF24W.

Set an element of the connection profile on the MRF24W.

Module

Wi-Fi Connection Profile ( see page 637)

Description

650

11.1 Wi-Fi Connection Profile Microchip TCP/IP Stack Help Connection Profile Internal Members

11.1.2.1

LowLevel_CPGetElement Function

File

WFConnectionProfile.c

C static void

LowLevel_CPGetElement(

UINT8 CpId,

UINT8 elementId,

UINT8 * p_elementData,

UINT8 elementDataLength,

UINT8 dataReadAction

);

Returns

None.

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.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId elementId p_elementData elementDataLength dataReadAction

Description

Connection Profile ID

Element that is being read

Pointer to where element data will be written

Number of element data bytes that will be read

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.

11.1.2.2

LowLevel_CPSetElement Function

File

WFConnectionProfile.c

C static void

LowLevel_CPSetElement(

UINT8 CpId,

UINT8 elementId,

UINT8 * p_elementData,

UINT8 elementDataLength

);

Returns

None.

Description

LOCAL FUNCTION PROTOTYPES

All Connection Profile 'Set Element' functions call this function to construct the management message. The caller must fix up

651

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members any endian issues prior to calling this function.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId elementId p_elementData elementDataLength

Description

Connection Profile ID

Element that is being set

Pointer to element data

Number of bytes pointed to by p_elementData

11.1.3

Macros

Macros

Name

RAW_MGMT_RX_ID ( see page 652)

Description

This is macro RAW_MGMT_RX_ID.

Module

Wi-Fi Connection Profile ( see page 637)

11.1.3.1

RAW_MGMT_RX_ID Macro

File

WFConnectionProfile.c

#define

RAW_MGMT_RX_ID RAW_RX_ID

Description

This is macro RAW_MGMT_RX_ID.

11.2

Wi-Fi Connection Algorithm

Module

WF_CAGetBeaconTimeout ( see page 654)

Description

The connection algorithm is used to fine-tune the MRF24WB0M / MRF24WG0M algorithm used in the connection process.

The connection algorithm can only be changed when the MRF24WB0M / MRF24WG0M is not connected to an 802.11

network.

652

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

11.2.1

Connection Algorithm Public Members

Functions

Name Description

Reads the beacon timeout value.

Reads the Connection Algorithm beacon timeout action.

WF_CAGetBeaconTimeoutAction

( see page 655)

WF_CAGetChannelList ( see page 655)

Gets the channel list.

Not currently supported

WF_CAGetConnectionProfileList

( see page 656)

WF_CAGetDeauthAction ( see page 656)

WF_CAGetElements ( see page

657)

Reads the Connection Algorithm deauth action.

Reads all Connection Algorithm elements.

WF_CAGetEventNotificationAction

( see page 657)

Reads the Connection Algorithm event notification action.

Gets the listen ( see page 180) interval.

WF_CAGetListenInterval ( see page 658)

WF_CAGetListRetryCount ( see page 659)

Gets the list retry count

WF_CAGetMaxChannelTime ( see page 659)

WF_CAGetMinChannelTime ( see page 660)

WF_CAGetProbeDelay ( see page 660)

Gets the Max Channel Time (in milliseconds)

Gets the current Connection Algorithm minimum channel time.

Gets the Probe Delay (in microseconds)

WF_CAGetRssi ( see page 661)

Gets the RSSI threshold

WF_CAGetScanCount ( see page 661)

Gets the scan count

WF_CAGetScanType ( see page

662)

Gets the Connection Algorithm scan type

Sets the beacon timeout value.

WF_CASetBeaconTimeout ( see page 662)

WF_CASetBeaconTimeoutAction

( see page 663)

Action to take if a connection is lost due to a beacon timeout.

Sets the channel list.

WF_CASetChannelList ( see page 663)

WF_CASetConnectionProfileList

( see page 664)

WF_CASetDeauthAction ( see page 664)

Not currently supported

Sets the DeauthAction used by the Connection Algorithm.

WF_CASetElements ( see page

665)

Writes all Connection Algorithm elements.

WF_CASetEventNotificationAction

( see page 665)

Sets the WiFi events that the host wishes to be notified of.

Sets the listen ( see page 180) interval.

WF_CASetListenInterval ( see page 666)

WF_CASetListRetryCount ( see page 667)

Sets the list retry count

653

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

Module

Wi-Fi Connection Algorithm ( see page 652)

Structures

WF_CASetMaxChannelTime ( see page 667)

WF_CASetMinChannelTime ( see page 668)

WF_CASetProbeDelay ( see page 668)

Sets the maximum channel time (in milliseconds)

Sets the minimum channel time (in milliseconds)

Sets the Probe Delay (in microseconds)

WF_CASetRssi ( see page 669)

Sets the RSSI threshold

WF_CASetScanCount ( see page 669)

Sets the scan count

WF_CASetScanType ( see page

670)

Sets the Connection Algorith scan type

WF_CAGetDtimInterval ( see page 672)

WF_CASetDtimInterval ( see page 673)

Gets the dtim interval for MRF24WG0MA/B.

Sets the dtim interval for MRF24WG0MA/B.

WF_CAGetBeaconPeriod ( see page 673)

WF_CASetBeaconPeriod ( see page 673)

Retrieves beacon period in Adhoc start mode for MRF24WG0MA/B.

Sets the beacon period in Adhoc start mode for MRF24WG0MA/B

Name

WFCAElementsStruct ( see page 670)

Description

Connection Algorithm Elements

Description

The following functions and variables are available to the stack application.

11.2.1.1

WF_CAGetBeaconTimeout Function

File

WFApi.h

C void

WF_CAGetBeaconTimeout(

UINT8 * p_beaconTimeout

);

Returns

None.

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.

654

11.2 Wi-Fi Connection Algorithm

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_beaconTimeout

Microchip TCP/IP Stack Help Connection Algorithm Public Members

Description

Pointer where beacon timeout value is written

11.2.1.2

WF_CAGetBeaconTimeoutAction Function

File

WFApi.h

C void

WF_CAGetBeaconTimeoutAction(

UINT8 * p_beaconTimeoutAction

);

Returns

None.

Description

Gets the Beacon Timeout Action used by the Connection Algorithm.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_beaconTimeoutAction will be either

Description

Pointer where returned value is written. The value

• WF_ATTEMPT_TO_RECONNECT

• WF_DO_NOT_ATTEMPT_TO_RECONNECT

11.2.1.3

WF_CAGetChannelList Function

File

WFApi.h

C void

WF_CAGetChannelList(

UINT8 * p_channelList,

UINT8 * p_numChannels

);

Returns

None.

Description

Gets the Channel List used by the Connection Algorithm.

655

11.2 Wi-Fi Connection Algorithm

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_channelList p_numChannels

Microchip TCP/IP Stack Help Connection Algorithm Public Members

Description

Pointer to where channel list will be returned

Pointer to where number of channels in list will be returned

11.2.1.4

WF_CAGetConnectionProfileList Function

File

WFApi.h

C void

WF_CAGetConnectionProfileList(

UINT8 cpList[WF_CP_LIST_LENGTH]

);

Returns

None

Description

Not currently supported

Remarks

Not currently supported. The list size is always WF_CP_LIST_SIZE.

Preconditions

MACInit must be called first.

Parameters

cpList

Description

Array of connection profile ID's used to create CP list

11.2.1.5

WF_CAGetDeauthAction Function

File

WFApi.h

C void

WF_CAGetDeauthAction(

UINT8 * p_deauthAction

);

Returns

None.

Description

Gets the DeauthAction used by the Connection Algorithm.

Remarks

None.

656

11.2 Wi-Fi Connection Algorithm

Preconditions

MACInit must be called first.

Parameters

p_deauthAction be either

Microchip TCP/IP Stack Help Connection Algorithm Public Members

Description

Pointer where returned value is written. The value will

• WF_ATTEMPT_TO_RECONNECT

• WF_DO_NOT_ATTEMPT_TO_RECONNECT

11.2.1.6

WF_CAGetElements Function

File

WFApi.h

C void

WF_CAGetElements(

tWFCAElements * p_elements

);

Returns

None

Description

Sends a message to the MRF24W which requests all the Connection Algorithm elements.

Remarks

None

Preconditions

MACInit must be called first.

Parameters

p_elements

Description

Pointer to the output structure (tWFCAElements) where the connection algorithm elements are written.

11.2.1.7

WF_CAGetEventNotificationAction Function

File

WFApi.h

C void

WF_CAGetEventNotificationAction(

UINT8 * p_eventNotificationAction

);

Returns

None.

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:

657

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

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

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_eventNotificationAction

Description

Pointer to where returned value is written.

11.2.1.8

WF_CAGetListenInterval Function

File

WFApi.h

C void

WF_CAGetListenInterval(

UINT16 * p_listenInterval

);

Returns

None.

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 MRF24W wakes up every 100ms to receive buffered messages.

...

MRF24W wakes up every 200ms to receive buffered messages.

...

65535 MRF24W wakes up every 6535.5 seconds (~109 minutes) to receive buffered messages.

Remarks

None.

Preconditions

MACInit must be called first. Only used when PS Poll mode is enabled.

Parameters

p_listenInterval

Description

Pointer to where listen ( see page 180) interval is returned

658

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

11.2.1.9

WF_CAGetListRetryCount Function

File

WFApi.h

C void

WF_CAGetListRetryCount(

UINT8 * p_listRetryCount

);

Returns

None

Description

See description in WF_CASetListRetryCount ( see page 667)()

Remarks

None

Preconditions

MACInit must be called first.

Parameters

p_listRetryCount

Description

Pointer to where list retry count is written.

11.2.1.10

WF_CAGetMaxChannelTime Function

File

WFApi.h

C void

WF_CAGetMaxChannelTime(

UINT16 * p_minChannelTime

);

Returns

None

Description

Gets the maximum time the connection manager waits for a probe response after sending a probe request.

Remarks

Default is 400ms

Preconditions

MACInit must be called first.

Parameters

p_maxChannelTime

Description

Pointer where maximum channel time is written

659

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

11.2.1.11

WF_CAGetMinChannelTime Function

File

WFApi.h

C void

WF_CAGetMinChannelTime(

UINT16 * p_minChannelTime

);

Returns

None

Description

Gets the minimum time the connection manager waits for a probe response after sending a probe request.

Remarks

None

Preconditions

MACInit must be called first.

Parameters

p_minChannelTime

Description

Pointer where minimum time to wait for a probe response (in milliseconds) will be written.

11.2.1.12

WF_CAGetProbeDelay Function

File

WFApi.h

C void

WF_CAGetProbeDelay(

UINT16 * p_probeDelay

);

Returns

None

Description

The number of microseconds to delay before transmitting a probe request following the channel change event.

Remarks

Default is 20uS

Preconditions

MACInit must be called first.

Parameters

p_probeDelay

Description

Pointer to where probe delay is written

660

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

11.2.1.13

WF_CAGetRssi Function

File

WFApi.h

C void

WF_CAGetRssi(

UINT8 * p_rssi

);

Returns

None

Description

See WF_CASetRssi ( see page 669). 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.

Remarks

Default is 255

Preconditions

MACInit must be called first.

Parameters

p_rssi

Description

Pointer to where RSSI value is written

11.2.1.14

WF_CAGetScanCount Function

File

WFApi.h

C void

WF_CAGetScanCount(

UINT8 * p_scanCount

);

Returns

None

Description

The number of times the Connection Manager will scan a channel while attempting to find a particular WiFi network.

Remarks

Default is 1

Preconditions

MACInit must be called first.

Parameters

p_scanCount

Description

Pointer to where scan count is written

661

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

11.2.1.15

WF_CAGetScanType Function

File

WFApi.h

C void

WF_CAGetScanType(

UINT8 * p_scanType

);

Returns

None

Description

Reads the current Connection Algorithm scan type. In active scan, STA will transmit probe request frames and AP/routers will respond by transmitting probe response frames. For AP/Router with hidden SSID, active scan is used. In passive scan,

AP/router will continuously transmit beacon frames for every beacon interval (BI), any STAs may/will receive these beacons and know of existence of this AP/router.

Remarks

Active scanning causes the MRF24W to send probe requests. Passive scanning implies the MRF24W only listens for beacons. Default is WF_ACTIVE_SCAN.

Preconditions

MACInit must be called first.

Parameters

p_scanType

Description

Pointer where Connection Algorithm scan type is written. Either

WF_ACTIVE_SCAN or WF_PASSIVE_SCAN.

11.2.1.16

WF_CASetBeaconTimeout Function

File

WFApi.h

C void

WF_CASetBeaconTimeout(

UINT8 beaconTimeout

);

Returns

None.

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.

662

11.2 Wi-Fi Connection Algorithm

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

beaconTimeout

Microchip TCP/IP Stack Help Connection Algorithm Public Members

Description

Number of beacons that can be missed before the action in beaconTimeoutAction is taken.

11.2.1.17

WF_CASetBeaconTimeoutAction Function

File

WFApi.h

C void

WF_CASetBeaconTimeoutAction(

UINT8 beaconTimeoutAction

);

Returns

None.

Description

Sets the Beacon Timeout Action used by the Connection Algorithm.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

beaconTimeoutAction to a beacon timeout. Choices are either

Description

Action to take if a connection is lost due

• WF_ATTEMPT_TO_RECONNECT

• WF_DO_NOT_ATTEMPT_TO_RECONNECT

11.2.1.18

WF_CASetChannelList Function

File

WFApi.h

C void

WF_CASetChannelList(

UINT8 * p_channelList,

UINT8 numChannels

);

Returns

None.

663

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

Description

Sets the Channel List used by the Connection Algorithm.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_channelList numChannels

Description

Pointer to channel list.

Number of channels in p_channelList. If set to 0, the MRF24W will use all valid channels for the current regional domain.

11.2.1.19

WF_CASetConnectionProfileList Function

File

WFApi.h

C void

WF_CASetConnectionProfileList(

UINT8 cpList[WF_CP_LIST_LENGTH]

);

Returns

None

Description

Not currently supported

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.

Preconditions

MACInit must be called first.

Parameters

cpList

Description

Array of connection profile ID's used to create CP list

11.2.1.20

WF_CASetDeauthAction Function

File

WFApi.h

C void

WF_CASetDeauthAction(

UINT8 deauthAction

);

Returns

None.

664

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

Description

Action to take if a connection is lost due to receiving a deauthentification message from an AP.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

deauthAction

Allowable values are

Description

Action to take in the event of a deauthentication.

• WF_ATTEMPT_TO_RECONNECT

• WF_DO_NOT_ATTEMPT_TO_RECONNECT

11.2.1.21

WF_CASetElements Function

File

WFApi.h

C void

WF_CASetElements(

tWFCAElements * p_elements

);

Returns

None

Description

Connection Algorithm Functions

Sends a message to the MRF24W which sets all the Connection Algorithm elements.

Remarks

None

Preconditions

MACInit must be called first.

Parameters

p_elements

Description

Pointer to the input structure (tWFCAElements) containing the connection algorithm elements.

11.2.1.22

WF_CASetEventNotificationAction Function

File

WFApi.h

C void

WF_CASetEventNotificationAction(

UINT8 eventNotificationAction

);

665

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

Returns

None.

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

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

eventNotificationAction

Description

Bit mask indicating which events the host wants to be notifed of.

11.2.1.23

WF_CASetListenInterval Function

File

WFApi.h

C void

WF_CASetListenInterval(

UINT16 listenInterval

);

Returns

None.

Description

Sets the listen ( see page 180) interval used by the Connection Algorithm. This value is measured in 100ms intervals, the

default beacon period of APs.

Value Description

MRF24W wakes up every 100ms to receive buffered messages.

MRF24W wakes up every 200ms to receive buffered messages.

...

65535 MRF24W wakes up every 6535.5 seconds (~109 minutes) to receive buffered messages.

Remarks

None.

666

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

Preconditions

MACInit must be called first. Only used when PS Poll mode is enabled.

Parameters

listenInterval

Description

Number of 100ms intervals between instances when the MRF24W wakes up to receive buffered messages from the network.

11.2.1.24

WF_CASetListRetryCount Function

File

WFApi.h

C void

WF_CASetListRetryCount(

UINT8 listRetryCount

);

Returns

None

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 ( see page 176) with

the current Connection Profile before giving up.

Remarks

None

Preconditions

MACInit must be called first.

Parameters

listRetryCount

Description

0 to 254 or WF_RETRY_FOREVER (255)

11.2.1.25

WF_CASetMaxChannelTime Function

File

WFApi.h

C void

WF_CASetMaxChannelTime(

UINT16 minChannelTime

);

Returns

None

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.

667

11.2 Wi-Fi Connection Algorithm

Remarks

Default is 400ms

Preconditions

MACInit must be called first.

Parameters

maxChannelTime

Microchip TCP/IP Stack Help Connection Algorithm Public Members

Description

Maximum time to wait for a probe response (in milliseconds)

11.2.1.26

WF_CASetMinChannelTime Function

File

WFApi.h

C void

WF_CASetMinChannelTime(

UINT16 minChannelTime

);

Returns

None

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.

Remarks

Default is 200ms

Preconditions

MACInit must be called first.

Parameters

minChannelTime

Description

Minimum time to wait for a probe response (in milliseconds)

11.2.1.27

WF_CASetProbeDelay Function

File

WFApi.h

C void

WF_CASetProbeDelay(

UINT16 probeDelay

);

Returns

None

Description

The number of microseconds to delay before transmitting a probe request following the channel change event.

668

11.2 Wi-Fi Connection Algorithm

Remarks

Default is 20uS

Preconditions

MACInit must be called first.

Parameters

probeDelay

Microchip TCP/IP Stack Help Connection Algorithm Public Members

Description

Desired probe delay

11.2.1.28

WF_CASetRssi Function

File

WFApi.h

C void

WF_CASetRssi(

UINT8 rssi

);

Returns

None

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 (MRF24WB), 1 - 128 (MRF24WG): Only connect ( see page 176) 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.

Remarks

Default is 255

Preconditions

MACInit must be called first.

Parameters

scanCount

Description

Desired scan count

11.2.1.29

WF_CASetScanCount Function

File

WFApi.h

C void

WF_CASetScanCount(

UINT8 scanCount

);

Returns

None

669

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

Description

The number of times the Connection Manager will scan a channel while attempting to find a particular WiFi network.

Remarks

Default is 1

Preconditions

MACInit must be called first.

Parameters

scanCount

Description

Desired scan count

11.2.1.30

WF_CASetScanType Function

File

WFApi.h

C void

WF_CASetScanType(

UINT8 scanType

);

Returns

None

Description

Configures the Connection Algorithm for the desired scan type. In active scan, STA will transmit probe request frames and

AP/routers will respond by transmitting probe response frames. For AP/Router with hidden SSID, active scan is used. In passive scan, AP/router will continuously transmit beacon frames for every beacon interval (BI), any STAs may/will receive these beacons and know of existence of this AP/router.

Remarks

Active scanning causes the MRF24W to send probe requests. Passive scanning implies the MRF24W only listens for beacons. Default is WF_ACTIVE_SCAN.

Preconditions

MACInit must be called first.

Parameters

scanType

Description

Desired scan type. Either WF_ACTIVE_SCAN or WF_PASSIVE_SCAN.

11.2.1.31

WFCAElementsStruct Structure

File

WFApi.h

C struct

WFCAElementsStruct {

UINT16 listenInterval;

UINT8 scanType;

UINT8 rssi;

UINT8 connectionProfileList[WF_CP_LIST_LENGTH];

UINT8 listRetryCount;

UINT8 eventNotificationAction;

670

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

UINT8 beaconTimeoutAction;

UINT8 deauthAction;

UINT8 channelList[WF_CHANNEL_LIST_LENGTH];

UINT8 numChannelsInList;

UINT8 beaconTimeout;

UINT8 scanCount;

UINT8 pad1;

UINT16 minChannelTime;

UINT16 maxChannelTime;

UINT16 probeDelay;

UINT16 dtimInterval;

UINT16 beaconPrd;

};

Members

UINT16 listenInterval;

UINT8 scanType;

UINT8 rssi;

Description

This parameter is only used when PS Poll mode is enabled. See

WF_PsPollEnable ( see page 699)(). Number of 100ms intervals between

instances when the MRF24W 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 ( see page 180) interval

in terms of Beacon Periods, which are typically 100ms. If the MRF24W 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 MRF24W will automatically reconnect to the network with the new Beacon Period value. This may cause a temporary loss of data packets.

WF_ACTIVE_SCAN (Probe Requests transmitted out) or

WF_PASSIVE_SCAN (listen ( see page 180) only for beacons received)

Default: WF_ACTIVE_SCAN

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;

UINT8 beaconTimeoutAction;

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.

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

671

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Public Members

UINT8 channelList[WF_CHANNEL_LIST_LENGTH];

UINT8 numChannelsInList;

UINT8 beaconTimeout;

UINT8 scanCount;

UINT16 minChannelTime;

UINT16 maxChannelTime;

UINT16 probeDelay;

UINT16 dtimInterval;

UINT16 beaconPrd;

Description

Connection Algorithm Elements

List of one or more channels that the MRF24W 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 MRF24W (set at manufacturing).

Number of channels in channelList. If set to 0 then the MRF24W will populate the list with all valid channels for the regional domain.

Default: The number of valid channels for the regional domain of the

MRF24W (set at manufacturing).

Specifies the number of beacons that can be missed before the action described in beaconTimeoutAction is taken.

The number of times to scan a channel while attempting to find a particular access point.

Default: 1

Default: 200ms

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

The number of microseconds to delay before transmitting a probe request following the channel change event.

Default: 20us

Default : 4

Default : 100 (ms)

11.2.1.32

WF_CAGetDtimInterval Function

File

WFApi.h

C void

WF_CAGetDtimInterval(

UINT16 * p_dtimInterval

);

Returns

None.

Description

Gets the DTIM Interval used by the Connection Algorithm for MRF24WG0MA/B.

Remarks

None.

Preconditions

MACInit must be called first. Only used when PS Poll mode is enabled.

672

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help

11.2.1.33

WF_CASetDtimInterval Function

File

WFApi.h

C void

WF_CASetDtimInterval(

UINT16 dtimInterval

);

Returns

None.

Description

Sets the dtim interval used by the Connection Algorithm for MRF24WG0MA/B.

Remarks

None.

Preconditions

MACInit must be called first. Only used when PS Poll mode is enabled.

11.2.1.34

WF_CAGetBeaconPeriod Function

File

WFApi.h

C void

WF_CAGetBeaconPeriod(

UINT16 * beaconPeriod

);

Returns

None.

Description

Gets Beacon period in Adhoc start mode for MRF24WG0MA/B.

Remarks

None.

Preconditions

MACInit must be called first.

11.2.1.35

WF_CASetBeaconPeriod Function

File

WFApi.h

C void

WF_CASetBeaconPeriod(

UINT16 beaconPeriod

);

Connection Algorithm Public Members

673

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Internal Members

Returns

None.

Description

Sets the beacon period used by the Connection Algorithm for MRF24WG0MA/B.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

beaconPeriod

Description

beacon period in adhoc start mode by ms resoluation

11.2.2

Connection Algorithm Internal Members

Functions

Name

LowLevel_CAGetElement ( see page 674)

LowLevel_CASetElement ( see page 675)

SetEventNotificationMask ( see page 675)

Description

Get an element of the connection algorithm on the MRF24W.

Set an element of the connection algorithm on the MRF24W.

Sets the event notification mask.

Module

Wi-Fi Connection Algorithm ( see page 652)

Description

The following functions and variables are designated as internal to the module.

11.2.2.1

LowLevel_CAGetElement Function

File

WFConnectionAlgorithm.c

C static void

LowLevel_CAGetElement(

UINT8 elementId,

UINT8 * p_elementData,

UINT8 elementDataLength,

UINT8 dataReadAction

);

Returns

None.

Description

Low-level function to send the appropriate management message to the MRF24W to get the Connection Algorithm element.

674

11.2 Wi-Fi Connection Algorithm Microchip TCP/IP Stack Help Connection Algorithm Internal Members

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.

Preconditions

MACInit must be called first.

Parameters

elementId p_elementData elementDataLength dataReadAction

Description

Element that is being read

Pointer to where element data will be written

Number of element data bytes that will be read

11.2.2.2

LowLevel_CASetElement Function

File

WFConnectionAlgorithm.c

C static void

LowLevel_CASetElement(

UINT8 elementId,

UINT8 * p_elementData,

UINT8 elementDataLength

);

Returns

None.

Description

LOCAL FUNCTION PROTOTYPES

Low-level function to send the appropriate management message to the MRF24W to set the Connection Algorithm element.

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.

Preconditions

MACInit must be called first.

Parameters

elementId p_elementData elementDataLength

Description

Element that is being set

Pointer to element data

Number of bytes pointed to by p_elementData

11.2.2.3

SetEventNotificationMask Function

File

WFConnectionAlgorithm.c

675

11.3 Wi-Fi Connection Manager Microchip TCP/IP Stack Help

C static void

SetEventNotificationMask(

UINT8 eventNotificationBitMask

);

Returns

None.

Description

Sets the event notification mask for the Connection Algorithm. Allowable values are:

Connection Manager Public Members

Value

0x01

0x02

0x04

0x08

0x10

0x1f

Event

WF_NOTIFY_CONNECTION_ATTEMPT_SUCCESSFUL

WF_NOTIFY_CONNECTION_ATTEMPT_FAILED

WF_NOTIFY_CONNECTION_TEMPORARILY_LOST

WF_NOTIFY_CONNECTION_PERMANENTLY_LOST

WF_NOTIFY_CONNECTION_REESTABLISHED

WF_NOTIFY_ALL_EVENTS

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

eventNotificationBitMask

Description

Bit mask defining which events the host will be notified of.

11.3

Wi-Fi Connection Manager

Module

The connection manager uses the connection algorithm and one or more connection profiles to connect ( see page 176) to

Description

a network.

11.3.1

Connection Manager Public Members

Functions

Name

WF_CMConnect ( see page

677)

WF_CMDisconnect ( see page 678)

Description

Commands the MRF24W to start a connection.

Commands the MRF24W to close any open connections and/or to cease

attempting to connect ( see page 176).

676

11.3 Wi-Fi Connection Manager Microchip TCP/IP Stack Help Connection Manager Public Members

WF_CMGetConnectionState

( see page 678)

Returns the current connection state. Caution when using

WF_CMGetConnectionState, as it may cause redirection issues when using iPhone iOS6.1, even though redirection on laptop is functional. Users are encouraged to use 1 profile ID for MRF24W based on v5 stack SW. This function is retained for backward compatibility. In v6 stack SW, we are keeping to 1 profile ID for MRF24W and changing stack SW to have capability to handle multiple profile IDs.

WF_CMGetConnectContext ( see page 678)

Retrieves WF connection context for MRF24WG0MA/B

WF_CMCheckConnectionState

( see page 679)

Returns the current connection state.

Module

Wi-Fi Connection Manager ( see page 676)

Description

The following functions and variables are available to the stack application.

11.3.1.1

WF_CMConnect Function

File

WFApi.h

C void

WF_CMConnect(

UINT8 CpId

);

Returns

None.

Description

Connection Manager Functions

Directs the Connection Manager to scan for and connect ( see page 176) to a WiFi network. This function does not wait

until the connection attempt is successful, but returns immediately. See WF_ProcessEvent ( see page 717) 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.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId

Description

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 ( see page 176), starting with the

first Connection Profile in the list.

677

11.3 Wi-Fi Connection Manager Microchip TCP/IP Stack Help Connection Manager Public Members

11.3.1.2

WF_CMDisconnect Function

File

WFApi.h

UINT16 WF_CMDisconnect();

Returns

Operation results. Success or Failure

Description

Directs the Connection Manager to close any open connection or connection attempt in progress. No further attempts to

connect ( see page 176) are taken until WF_CMConnect ( see page 677)() is called.

Remarks

None.

Preconditions

MACInit must be called.

11.3.1.3

WF_CMGetConnectionState Function

File

WFApi.h

C void

WF_CMGetConnectionState(

UINT8 * p_state,

UINT8 * p_currentCpId

);

Returns

None.

Description

Returns the current connection state.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_state p_currentCpId

Description

Pointer to location where connection state will be written

Pointer to location of current connection profile ID that is being queried.

11.3.1.4

WF_CMGetConnectContext Function

File

WFApi.h

678

11.4 Wi-Fi Scan Microchip TCP/IP Stack Help

C void

WF_CMGetConnectContext(

tWFConnectContext * p_ctx

);

Returns

None.

Description

Retrieve connection context

Retrieves WF connection context for MRF24WG0MA/B

Remarks

None.

Preconditions

MACInit must be called first.

11.3.1.5

WF_CMCheckConnectionState Function

File

WFApi.h

C void

WF_CMCheckConnectionState(

UINT8 * p_state,

UINT8 * p_currentCpId

);

Returns

None.

Description

Returns the current connection state.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_state p_currentCpId

Description

Pointer to location where connection state will be written

Pointer to location of current connection profile ID that is being queried.

11.4

Wi-Fi Scan

Module

WF_ScanGetResult ( see page 681)

Description

If the application already knows the network SSID that it wants to join than it can set up a connection profile with that

679

11.4 Wi-Fi Scan Microchip TCP/IP Stack Help Scan Public Members information and attempt to join the network. However, there are applications that first need to dynamically determine what infrastructure, adhoc or Wi-Fi Direct networks are in the area, and then decide which network to join. The scan API functions are used to gather this information.

There are 2 types of scan operations

• Active Scan

STA will transmit probe request frames and AP/routers will respond by transmitting probe response frames. For AP/Router with hidden SSID, active scan is used.

• Passive Scan

AP/router will continuously transmit beacon frames for every beacon interval (BI), any STAs may/will receive these beacons and know of existence of this AP/router.

11.4.1

Scan Public Members

Functions

Name Description

WF_Scan ( see page 680)

Commands the MRF24W to start a scan operation. This will generate the

WF_EVENT_SCAN_RESULTS_READY event.

Read scan results back from MRF24W.

Module

Wi-Fi Scan ( see page 679)

Description

The following functions and variables are available to the stack application.

11.4.1.1

WF_Scan Function

File

WFApi.h

UINT16 WF_Scan(

UINT8 CpId

);

Returns

Operation results. Success or Failure

Description

Scan Functions

Directs the MRF24W 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 ( see page 681)().

Scan results are retained on the MRF24W until:

1. Calling WF_Scan() again (after scan results returned from previous call).

2. MRF24W reset.

680

11.4 Wi-Fi Scan Microchip TCP/IP Stack Help Scan Public Members

MRF24WB0M & MRF24WG0M support up to max of 60 scan results (SSIDs).

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId

Description

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 MRF24W’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.

11.4.1.2

WF_ScanGetResult Function

File

WFApi.h

C void

WF_ScanGetResult(

UINT8 listIndex,

tWFScanResult * p_scanResult

);

Returns

None.

Description

After a scan has completed this function is used to read one or more of the scan results from the MRF24W. The scan results will be written contiguously starting at p_scanResult (see tWFScanResult structure for format of scan result). MRF24WB0M

& MRF24WG0M support up to max of 60 scan results (SSIDs).

Remarks

p_scanResult->rssi contains signal strength RSSI. MRF24WB : RSSI_MAX (200) , RSSI_MIN (106). MRF24WG :

RSSI_MAX (128) , RSSI_MIN (43).

Preconditions

MACInit must be called first. WF_EVENT_SCAN_RESULTS_READY event must have already occurrerd.

681

Microchip TCP/IP Stack Help Wired Equivalent Privacy (WEP) 11.5 Wi-Fi Security

Parameters

listIndex p_scanResult

Description

Index (0-based list) of the scan entry to retrieve.

Pointer to location to store the scan result structure

11.5

Wi-Fi Security

Module

WF_CPGetWepKeyType ( see page 684)

Description

This section elaborates on the various security modes supported by MRF24WB0M and MRF24WG0M.

Security modes supported in

• Ad-hoc

OPEN, WEP

• SoftAP

OPEN, WEP

• Infrastructure

OPEN, WEP, WPA/WPA2, WPS

• Wi-Fi Direct

WPS

682

11.5 Wi-Fi Security Microchip TCP/IP Stack Help Wired Equivalent Privacy (WEP)

11.5.1

Wired Equivalent Privacy (WEP)

Functions

Name

Description

Gets the WEP key type for the specified Connection Profile ID.

WF_CPGetDefaultWepKeyIndex

( see page 684)

Returns the value of the active WEP keys to use. Only WEP key index 0 is used in RF module FW.

WF_CPSetDefaultWepKeyIndex

( see page 685)

Set up the WEP key index. Only WEP key index 0 is used in RF module FW.

WF_CPSetWepKeyType ( see page 685)

Sets the WEP key type for the specified Connection Profile ID.

Description

WIRED EQUIVALENT PRIVACY (WEP)

Security loop holes are present and this is not recommend!!!

WEP security modes supported are

• WF_SECURITY_WEP_40

WEP Encryption using 40 bit keys. Also known as WEP 64 keys.

This security method uses a 40 bit (10 Hex character) "secret key" and a 24 bit Initialization ( see page 143) Vector (IV).

• WF_SECURITY_WEP_104

WEP Encryption using 104 bit keys Also known as WEP 128 keys.

This security method uses a 104 bit (26 Hex Character) "secret key", and a 24 bit Initialization ( see page 143) Vector (IV).

MRF24W only accepts WEP hex keys (MY_DEFAULT_WEP_KEYS_40 or MY_DEFAULT_WEP_KEYS_104) and NOT

passphrase. Some Web sites offer this automatic WEP key generators, whereby WEP keys are generated from ordinary text called a passphrase.

WEP key types supported are

• WF_SECURITY_WEP_OPENKEY

Default

• WF_SECURITY_WEP_SHAREDKEY

Supported by MRF24WG0M.

Supported by MRF24WB0M (RF module FW version 0x1209 and later)

According to 802.11 specifications, WEP can have a total of 4 keys ( or 4 key indices ). However, in commercial products , only 1 key index (0) is really used. As an example, for iOS, Android and even Windows, there is probably no option to choose WEP key index. That implies they are using only 1 WEP key index.

683

11.5 Wi-Fi Security Microchip TCP/IP Stack Help Wired Equivalent Privacy (WEP)

11.5.1.1

WF_CPGetWepKeyType Function

File

WFApi.h

C void

WF_CPGetWepKeyType(

UINT8 CpId,

UINT8 * p_wepKeyType

);

Returns

None.

Description

Gets the WEP key type element for the specified Connection Profile. Allowable values are:

• WF_SECURITY_WEP_SHAREDKEY (0)

• WF_SECURITY_WEP_OPENKEY (1) - Default

Remarks

Before MRF24W is connected to the AP/Router, calling this function will always return WF_SECURITY_WEP_OPENKEY (1) as the default.

Preconditions

MACInit must be called first.

11.5.1.2

WF_CPGetDefaultWepKeyIndex Function

File

WFApi.h

C void

WF_CPGetDefaultWepKeyIndex(

UINT8 CpId,

UINT8 * p_defaultWepKeyIndex

);

Returns

None.

Description

Only applicable if the Connection Profile security type is either WF_SECURITY_WEP_40 or WF_SECURITY_WEP_104.

Since only WEP key index 0 is supported, this function is no longer needed.

Remarks

Note that only WEP key index 0 amongst AP manufacturers is typically used. Using any of the other three keys may be unpredictable from brand to brand.

Preconditions

MACInit must be called first.

Parameters

CpId p_defaultWepKeyIndex

Description

Connection Profile ID

Pointer to index of WEP key to use.

684

11.5 Wi-Fi Security

No longer supporting 4 WEP key indexes

3).

Microchip TCP/IP Stack Help Wi-Fi Protected Access (WPA/WPA2)

11.5.1.3

WF_CPSetDefaultWepKeyIndex Function

File

WFApi.h

C void

WF_CPSetDefaultWepKeyIndex(

UINT8 CpId,

UINT8 defaultWepKeyIndex

);

Returns

None.

Description

Only applicable if the Connection Profile security type is either WF_SECURITY_WEP_40 or WF_SECURITY_WEP_104.

Since only WEP key index 0 is supported, this function is no longer needed.

Remarks

Note that only WEP key index 0 amongst AP manufacturers is typically used. Using any of the other three keys may be unpredictable from brand to brand.

Preconditions

MACInit must be called first.

Parameters

CpId defaultWepKeyIndex

Description

Connection Profile ID

Use WEP key index 0. No longer supporting 4 WEP key indexes (0 - 3).

11.5.1.4

WF_CPSetWepKeyType Function

File

WFApi.h

C void

WF_CPSetWepKeyType(

UINT8 CpId,

UINT8 wepKeyType

);

Returns

None.

Description

Sets the WEP key type (WF_SECURITY_WEP_SHAREDKEY or WF_SECURITY_WEP_OPENKEY) for the specified

Connection Profile ID. Default WEP key type is WF_SECURITY_WEP_OPENKEY.

Remarks

None.

Preconditions

MACInit must be called first.

685

11.5 Wi-Fi Security Microchip TCP/IP Stack Help Wi-Fi Protected Access (WPA/WPA2)

11.5.2

Wi-Fi Protected Access (WPA/WPA2)

Functions

Name

WF_CPUpdatePMK ( see page 687)

WF_ConvPassphrase2Key

( see page 687)

pbkdf2_sha1 ( see page

688)

Description

Updates the PMK element in the connection profile ID retrieved out of 802.1x authentication process

Allow host to convert passphrase to key

This is function pbkdf2_sha1.

Description

Wi-Fi PROTECTED ACCESS (WPA/WPA2)

Refer to the Wi-Fi Protected Access (WPA) Enhanced Security Implementation Based on IEEE P802.11i standard.

Other equivalent WPA/WPA2 terminologies used are WPA - 4 way handshake or EAPOL - 4 way handshake or 802.1X

authentication.

Upon initial connection, after authentication followed by association, WPA/WPA2 EAPOL 4-way handshaking will takes place.

WPA/WPA2 security modes supported are

• WF_SECURITY_WPA_WITH_KEY

WPA-PSK Personal where binary key is given to MRF24W

• WF_SECURITY_WPA_WITH_PASS_PHRASE

WPA-PSK Personal where passphrase is given to MRF24W and it calculates the binary key

• WF_SECURITY_WPA2_WITH_KEY

WPA2-PSK Personal where binary key is given to MRF24W

• WF_SECURITY_WPA2_WITH_PASS_PHRASE

WPA2-PSK Personal where passphrase is given to MRF24W and it calculates the binary key

• WF_SECURITY_WPA_AUTO_WITH_KEY

WPA-PSK Personal or WPA2-PSK Personal where binary key is given and MRF24W will connect ( see page 176) at

highest level AP supports (WPA or WPA2)

• WF_SECURITY_WPA_AUTO_WITH_PASS_PHRASE

WPA-PSK Personal or WPA2-PSK Personal where passphrase is given to MRF24W and it calculates the binary key and connects at highest level AP supports (WPA or WPA2).

MRF24W can be configured to accept ( see page 174) either binary key or passphrase, through

MY_DEFAULT_WIFI_SECURITY_MODE compile-time definiton. The WPA/WPA2 authentication process involves key derivation from the given passphrase.

Since this key derivation process is computational intensive and requires memory space, options are given

• Host to derive the key from the passphrase

DERIVE_KEY_FROM_PASSPHRASE_IN_HOST needs to be enabled. Refer to function prototype pbkdf2_sha1 ( see page 688)() in WF_pbkdf2.c for the algorithm.

686

11.5 Wi-Fi Security Microchip TCP/IP Stack Help Wi-Fi Protected Access (WPA/WPA2)

In this scenario, MRF24W will generate an event (WF_EVENT_KEY_CALCULATION_REQUEST) to host (eg PIC32) and set g_WpsPassphrase.valid to TRUE. Upon receipt of this event, the host will execute the function

WF_ConvPassphrase2Key ( see page 687)() to convert the passphrase to key. Upon completion of this conversion, the

host will call WF_SetPSK ( see page 691)() to pass the converted key to MRF24W.

• MRF24W will handle the entire WPA/WPA2 passphase and then key derivation

MRF24WB0M consumes about ~32 seconds whereas MRF24WG0M will consume about ~25 seconds.

11.5.2.1

WF_CPUpdatePMK Function

File

WFApi.h

C void

WF_CPUpdatePMK(

UINT8 CpId,

UINT8 * pmk

);

Returns

None.

Description

Applicable for MRF24WG0M only. Updates the PMK element in the connection profile ID retrieved out of 802.1x

authentication process. This function is not used in the TCPIP demo apps.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

CpId pmk

Description

Connection Profile ID pairwise master key

11.5.2.2

WF_ConvPassphrase2Key Function

File

WFApi.h

C void

WF_ConvPassphrase2Key(

UINT8 key_len,

UINT8 * key,

UINT8 ssid_len,

UINT8 * ssid

);

Returns

None.

Description

DERIVE_KEY_FROM_PASSPHRASE_IN_HOST and __C32__ must be enabled. This function is called in WPS or WPA or

WPA2 security modes. Convert WPS/WPA/WPA2 passphrase to key. Allows host (eg PIC32) to perform conversion of the

687

11.5 Wi-Fi Security Microchip TCP/IP Stack Help Wi-Fi Protected Setup (WPS) passphrase to the key by itself instead of relying on RF module FW. This is recommended only for PIC microprocessors that has high computational bandwidth and sufficient memory space. As a benchmark, MRF24WB0M will take 32 sec and

MRF24WG0M will take 25 sec for this computation.

Remarks

MRF24W will generate an event (WF_EVENT_KEY_CALCULATION_REQUEST) to PIC32 and set g_WpsPassphrase.valid

to TRUE. Upon receipt of this event, PIC32 will invoke this function WF_ConvPassphrase2Key to convert the passphrase to

key. Once this conversion is completed, PIC32 will call WF_SetPSK ( see page 691) to pass the converted key to

MRF24W.

Preconditions

MACInit must be called first.

Parameters

key_len key ssid_len ssid

Description

key length passphrase as an input. key as an output ssid length ssid

11.5.2.3

pbkdf2_sha1 Function

File

WFApi.h

C void

pbkdf2_sha1(

const char

* passphrase,

const char

* ssid,

UINT16 ssid_len,

UINT16 iterations,

UINT8 * buf,

UINT16 buflen

);

Description

This is function pbkdf2_sha1.

11.5.3

Wi-Fi Protected Setup (WPS)

Functions

Name

WF_CPGetWPSCredentials

( see page 690)

WF_YieldPassphrase2Host

( see page 691)

WF_SetPSK ( see page

691)

Description

Gets the WPS credentials for the specified Connection Profile ID for

MRF24WG0MA/B.

Allows host to handle WPS WPA/WPA2-PSK passphrase

Sends PSK to module FW in WPS mode.

Description

Wi-Fi PROTECTED SETUP (WPS)

Refer to the Wi-Fi Protected Setup Specification Version 1.0h standard.

688

11.5 Wi-Fi Security Microchip TCP/IP Stack Help Wi-Fi Protected Setup (WPS)

WPS does not support ad hoc networks.

WPS will configure the network name SSID and security key for the AP and WPS client devices on a network. It supports the

WEP / WPA / WPA2 security methods.

2 methods are supported

• WPS-PBC (Push Button Configuration)

Users can connect ( see page 176) the device (MRF24WG0M) to the network and enable data encryption by pushing the

buttons on the AP and client device. Users do NOT need to know the SSID of the AP, however the users are required to be within close proximity of the AP to press the push button on the AP.

• WPS-PIN (Personal Information Number)

PIN is provided for each device which joins the network. Enter this PIN on the AP/Router (Registrar) and activate AP

(Registrar) first before MRF24WG0M attempts to connect ( see page 176). The last digit of the PIN is the checksum of the

first 7 digits of the PIN. This checksum must be correct, otherwise MRF24WG0M module will reject the PIN code.

To set up WPS-PBC, define

• MY DEFAULT_NETWORK_TYPE as CFG_WF_INFRASTRUCTURE

• MY_DEFAULT_SSID_NAME as ""

• MY_DEFAULT_WIFI_SECURITY_MODE as WF_SECURITY_WPS_PUSH_BUTTON

To set up WPS-PIN, define

• MY DEFAULT_NETWORK_TYPE as CFG_WF_INFRASTRUCTURE

• MY_DEFAULT_SSID_NAME to be the same SSSID as the AP/router

• MY_DEFAULT_WIFI_SECURITY_MODE as WF_SECURITY_WPS_PIN

• MY_DEFAULT_WPS_PIN to be the same as the AP/router PIN.

WPS protocol can be viewed as a security connection method, built upon the existing security modes WPA/WPA2. The protocol encompasses a M1-M8 message exchange process. Therefore additional time is consumed. The WPS specification specifies below:

1. Retransmission timeout = 5 sec

2. Individual message processing timeout = 15 sec

3. Overall timeout for entire protocol to complete = 2 min

To address this lengthy time required every single time the MRF24W is restarted, the function prototype

WF_SaveWPSCredentials() can be invoked. Basically what this function does is to retrieve WPS credentials from MRF24W and store these into global variable AppConfig. In this way, it makes the WPS credentials re-useable and shorten subsequent reconnection time. For an actual product, it is advised to add in a timeout such that the WPS credentials will need to be refreshed or updated periodically.

WPS protocol

The WPS protocol, which encompass WPA/WPA2 authentication process, involves key derivation from the given passphrase. Since this key derivation process is computational intensive and requires memory space, options are given

• Host to derive the key from the passphrase

DERIVE_KEY_FROM_PASSPHRASE_IN_HOST needs to be enabled. Refer to function prototype pbkdf2_sha1 ( see page 688)() in WF_pbkdf2.c for the algorithm.

In this scenario, WF_YieldPassphrase2Host ( see page 691)() will inform MRF24W that host wants to do conversion.

689

11.5 Wi-Fi Security Microchip TCP/IP Stack Help Wi-Fi Protected Setup (WPS)

MRF24W will generate an event (WF_EVENT_KEY_CALCULATION_REQUEST) to host (eg PIC32) and set

g_WpsPassphrase.valid to TRUE. Upon receipt of this event, the host will execute the function WF_ConvPassphrase2Key

( see page 687)() to convert the passphrase to key. Upon completion of this conversion, the host will call WF_SetPSK ( see page 691)() to pass the converted key to MRF24W.

• MRF24W will handle the entire WPA/WPA2 passphase and then key derivation

MRF24WB0M consumes about ~32 seconds whereas MRF24WG0M will consume about ~25 seconds.

Upon initial connection (after authentication followed by association), the subsequent process will take place.

• WPS M1-M8 exchanges

• WPA/WPA2 EAPOL 4-way handshaking

Below shows the WPS protocol

11.5.3.1

WF_CPGetWPSCredentials Function

File

WFApi.h

C void

WF_CPGetWPSCredentials(

UINT8 CpId,

tWFWpsCred * p_cred

);

Returns

None.

Description

Applicable for MRF24WG0M only. Gets the WPS credentials after WPS completed for MRF24WG0MA/B.

Remarks

None.

Preconditions

MACInit must be called first.

690

11.5 Wi-Fi Security

Parameters

CpId p_cred

Microchip TCP/IP Stack Help

Description

Connection Profile ID

Pointer to the credentials

WPA2 Enterprise

11.5.3.2

WF_YieldPassphrase2Host Function

File

WFApi.h

C void

WF_YieldPassphrase2Host();

Returns

None.

Description

WPS supporting Functions

DERIVE_KEY_FROM_PASSPHRASE_IN_HOST must be enabled. Applicable for MRF24WG0M only. This function is used only for WF_SECURITY_WPS_PUSH_BUTTON and WF_SECURITY_WPS_PIN security mode. Allows host to convert pass phrase to key in WPS WPA/WPA2-PSK

Remarks

None.

Preconditions

MACInit must be called first.

11.5.3.3

WF_SetPSK Function

File

WFApi.h

C void

WF_SetPSK(

UINT8 * psk

);

Returns

None.

Description

DERIVE_KEY_FROM_PASSPHRASE_IN_HOST must be enabled. Applicable for MRF24WG0M only. Sends PSK to module FW in WPS mode.

Remarks

This function is used in conjunction with WF_ConvPassphrase2Key ( see page 687)(). MRF24W will generate an event

(WF_EVENT_KEY_CALCULATION_REQUEST) to PIC32 and set g_WpsPassphrase.valid to TRUE. Upon receipt of this

event, PIC32 will invoke this function WF_ConvPassphrase2Key ( see page 687) to convert the passphrase to key. Once

this conversion is completed, PIC32 will call WF_SetPSK to pass the converted key to MRF24W.

Preconditions

MACInit must be called first.

691

11.6 Wi-Fi Tx Power Control Microchip TCP/IP Stack Help Tx Power Control Public Members

11.5.4

WPA2 Enterprise

WPA2 Enterprise

Special approval needs to be submitted to marketing.

Supported by MRF24WG0M only.

RF module FW versions will be even-numbered, such as 0x3108, 0x310a, etc.

Requires MLA v5.42.06 March 2013 release and future releases.

This security mode WPS Enterprise is used in WiFi Console. The security types supported are

• EAP-PEAP/MSCHAPv2

• EAP-TTLS/MSCHAPv2

11.6

Wi-Fi Tx Power Control

Module

WF_TxPowerGetMinMax ( see page 693)

Description

The API functions in this section are used to configure the MRF24WB0M / MRF24WG0M transmit (Tx) power control settings.

MRF24WB0M transmit power settings are from -10dBm to +10dBm.

MRF24WG0M transmit power settings are from 0dBm to +18dBm.

11.6.1

Tx Power Control Public Members

Functions

Name

WF_TxPowerSetMinMax ( see page 693)

WF_TxPowerGetFactoryMax

( see page 694)

WF_TxPowerGetMax ( see page 694)

WF_TxPowerSetMax ( see page 695)

Description

Gets the Tx min and max power on the MRF24WB0MA/B.

Sets the Tx min and max power on the MRF24WB0MA/B.

Retrieves the factory-set max Tx power from the MRF24WB0MA/B and

MRF24WG0MA/B.

Gets the Tx max power on the MRF24WG0MA/B.

Sets the Tx max power on the MRF24WG0MA/B.

Module

Wi-Fi Tx Power Control ( see page 692)

692

11.6 Wi-Fi Tx Power Control Microchip TCP/IP Stack Help

Description

The following functions and variables are available to the stack application.

Tx Power Control Public Members

11.6.1.1

WF_TxPowerGetMinMax Function

File

WFApi.h

C void

WF_TxPowerGetMinMax(

INT8 * p_minTxPower,

INT8 * p_maxTxPower

);

Returns

None.

Description

After initialization the MRF24WB0MA/B 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 ( see page 694)().

Remarks

No conversion of units needed, input to MRF24WB0MA/B is in dB.

Preconditions

MACInit must be called first.

Parameters

p_minTxPower p_maxTxPower

Description

Pointer to location to write the minTxPower

Pointer to location to write the maxTxPower

11.6.1.2

WF_TxPowerSetMinMax Function

File

WFApi.h

C void

WF_TxPowerSetMinMax(

INT8 minTxPower,

INT8 maxTxPower

);

Returns

None.

Description

factory-set value, which can be read via WF_TxPowerGetFactoryMax ( see page 694)().

Remarks

No conversion of units needed, input to MRF24WB0MA/B is in dB.

693

11.6 Wi-Fi Tx Power Control

Preconditions

MACInit must be called first.

Parameters

minTxPower maxTxPower

Microchip TCP/IP Stack Help Tx Power Control Public Members

Description

Desired minTxPower (-10 to 10dB)

Desired maxTxPower (-10 to 10dB)

11.6.1.3

WF_TxPowerGetFactoryMax Function

File

WFApi.h

C void

WF_TxPowerGetFactoryMax(

INT8 * p_factoryMaxTxPower

);

Returns

None.

Description

For MRF24WB, desired maxTxPower (-10 to 10 dBm), in 1dB steps For MRF24WG, desired maxTxPower ( 0 to 18 dBm), in

1dB steps

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_factoryMaxTxPower

Description

for MRF24WB, desired maxTxPower (-10 to 10 dBm), in 1dB steps for

MRF24WG, desired maxTxPower ( 0 to 18 dBm), in 1dB steps

11.6.1.4

WF_TxPowerGetMax Function

File

WFApi.h

C void

WF_TxPowerGetMax(

INT8 * p_maxTxPower

);

Returns

None.

Description

After initialization the MRF24WG0MA/B max Tx power is determined by a factory-set value. This function can set a different maximum Tx power levels. However, this function can never set a maximum Tx power greater than the factory-set value,

which can be read via WF_TxPowerGetFactoryMax ( see page 694)().

694

11.7 Wi-Fi Power Save Microchip TCP/IP Stack Help

Remarks

No conversion of units needed, input to MRF24WG0MA/B is in dBm.

Preconditions

MACInit must be called first.

Parameters

p_maxTxPower

Description

Pointer to location to write the maxTxPower

11.6.1.5

WF_TxPowerSetMax Function

File

WFApi.h

C void

WF_TxPowerSetMax(

INT8 maxTxPower

);

Returns

None.

Description

Tx Power Control Functions

which can be read via WF_TxPowerGetFactoryMax ( see page 694)().

Remarks

No conversion of units needed, input to MRF24WG0MA/B is in dBm.

Preconditions

MACInit must be called first.

Parameters

maxTxPower

Description

valid range (0 to 18 dBm)

11.7

Wi-Fi Power Save

Module

GetAppPowerSaveMode ( see page 701)

Functions

Name

SetAppPowerSaveMode ( see page 701)

Description

Returns state of power save mode

Enable or disable power save mode

695

11.7 Wi-Fi Power Save Microchip TCP/IP Stack Help

Macros

Name Description

REG_DISABLE_LOW_POWER_MASK

( see page 704)

This is macro REG_DISABLE_LOW_POWER_MASK.

Types

Name

tWFPsPwrMode ( see page

702) tWFPwrModeReq ( see page 702)

Description

Enumeration of valid values for WFSetPowerSaveMode()

This is type tWFPwrModeReq.

Variables

Name Description

g_AppPowerSaveModeEnabled

( see page 703)

This is variable g_AppPowerSaveModeEnabled.

g_powerSaveState ( see page 703)

LOCAL GLOBAL VARIABLES

This is variable g_psPollActive.

g_psPollActive ( see page

703) g_rxDtim ( see page 703)

This is variable g_rxDtim.

This is variable g_sleepNeeded.

g_sleepNeeded ( see page

704) gRFModuleVer1209orLater ( see page 704)

This is variable gRFModuleVer1209orLater.

Description

The MRF24WB0M / MRF24WG0M supports two power-saving modes – sleep and hibernate.

Mode

Sleep

Hibernate

Description

This mode is used when in PS Poll mode where the MRF24WB0M / MRF24WG0M 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 / MRF24WG0M 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.

This mode effectively turns off the LDO of the MRF24WB0M / MRF24WG0M for maximum power savings. MRF24WB0M / MRF24WG0M state is not retained, and when the MRF24WB0M /

MRF24WG0M is taken out of the Hibernate state it performs a reboot.

Hibernate mode is controlled by toggling the HIBERNATE pin on the MRF24WB0M /

MRF24WG0M module (high to enter hibernate, low to exit).

This mode should be used when the application allows for the MRF24WB0M / MRF24WG0M 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

696

11.7 Wi-Fi Power Save Microchip TCP/IP Stack Help Power Save Public Members 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).

11.7.1

Power Save Public Members

Functions

Name

WF_GetPowerSaveState ( see page 697)

WF_HibernateEnable ( see page 698)

WF_PsPollDisable ( see page 698)

WF_PsPollEnable ( see page 699)

Description

Returns current power-save state.

Puts the MRF24W into hibernate mode by setting HIBERNATE pin to HIGH.

Disables PS-Poll mode.

Enables PS Poll mode.

Module

SendPowerModeMsg ( see page 700)

Description

The following functions and variables are available to the stack application.

11.7.1.1

WF_GetPowerSaveState Function

File

WFApi.h

C void

WF_GetPowerSaveState(

UINT8 * p_powerSaveState

);

Returns

None.

Description

Returns the current MRF24W power save state.

Value

WF_PS_HIBERNATE

WF_PS_PS_POLL_DTIM_ENABLED

WF_PS_PS_POLL_DTIM_DISABLED

WF_PS_POLL_OFF

Remarks

None.

Preconditions

MACInit must be called first.

Definition

MRF24W in hibernate state

MRF24W in PS-Poll mode with DTIM enabled

MRF24W in PS-Poll mode with DTIM disabled

MRF24W is not in any power-save state

697

11.7 Wi-Fi Power Save

Parameters

p_powerSaveState

Microchip TCP/IP Stack Help

Description

Pointer to where power state is written

Power Save Public Members

11.7.1.2

WF_HibernateEnable Function

File

WFApi.h

C void

WF_HibernateEnable();

Returns

None.

Description

Enables Hibernate mode on the MRF24W, which effectively turns off the device for maximum power savings. HIBERNATE pin on MRF24W is set to HIGH.

MRF24W state is not maintained when it transitions to hibernate mode. To remove the MRF24W from hibernate mode call

WF_Init().

Remarks

Note that because the MRF24W 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 MRF24W 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 MRF24W without needing a host reset.

Preconditions

MACInit must be called first.

11.7.1.3

WF_PsPollDisable Function

File

WFApi.h

C void

WF_PsPollDisable();

Returns

None.

Description

Power Management Functions

Disables PS Poll mode. The MRF24W will stay active and not go sleep.

Remarks

None.

Preconditions

MACInit must be called first.

698

11.7 Wi-Fi Power Save Microchip TCP/IP Stack Help Power Save Internal Members

11.7.1.4

WF_PsPollEnable Function

File

WFApi.h

C void

WF_PsPollEnable(

BOOL rxDtim

);

Returns

None.

Description

Enables PS Poll mode. PS-Poll (Power-Save Poll) is a mode allowing for longer battery life. The MRF24W coordinates with the Access Point to go to sleep and wake up at periodic intervals to check for data messages, which the Access Point will buffer. The listenInterval in the Connection Algorithm defines the sleep interval. By default, PS-Poll mode is disabled.

When PS Poll is enabled, the WF Host Driver will automatically force the MRF24W to wake up each time the Host sends Tx data or a control message to the MRF24W. When the Host message transaction is complete the MRF24W driver will automatically re-enable PS Poll mode.

When the application is likely to experience a high volume of data traffic then PS-Poll mode should be disabled for two reasons:

1. No power savings will be realized in the presence of heavy data traffic.

2. Performance will be impacted adversely as the WiFi Host Driver continually activates and deactivates PS-Poll mode via

SPI messages.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

rxDtim

Description

TRUE listens at the DTIM interval and FALSE listens at the CASetListenInterval

11.7.2

Power Save Internal Members

Functions

Name

SetPowerSaveState ( see page 700)

Description

Send power mode management message to the MRF24W.

Sets the desired power save state of the MRF24W.

Module

tWFPwrModeReq * p_powerMode

Description

The following functions and variables are designated as internal to the module.

699

11.7 Wi-Fi Power Save Microchip TCP/IP Stack Help Functions

11.7.2.1

SendPowerModeMsg Function

File

WFPowerSave.c

C static void

SendPowerModeMsg(

);

Returns

None.

Description

LOCAL FUNCTION PROTOTYPES

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_powerMode

Description

Pointer to tWFPwrModeReq ( see page 702) structure to send to MRF24W.

11.7.2.2

SetPowerSaveState Function

File

WFPowerSave.c

C void

SetPowerSaveState(

UINT8 powerSaveState

);

Returns

None.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

powerSaveState

Description

Value of the power save state desired.

700

11.7 Wi-Fi Power Save Microchip TCP/IP Stack Help

11.7.3

Functions

Functions

Name

GetAppPowerSaveMode ( see page 701)

SetAppPowerSaveMode ( see page 701)

Module

Returns state of global variable g_AppPowerSaveModeEnabled ( see page 703)

Description

Returns state of power save mode

Enable or disable power save mode

11.7.3.1

GetAppPowerSaveMode Function

File

WFPowerSave.c

BOOL GetAppPowerSaveMode();

Returns

None.

Description

Remarks

None.

11.7.3.2

SetAppPowerSaveMode Function

File

WFPowerSave.c

C void

SetAppPowerSaveMode(

BOOL state

);

Returns

None.

Description

Set or reset global variable g_AppPowerSaveModeEnabled ( see page 703) to enable or disable power save mode

Remarks

None.

Types

701

11.7 Wi-Fi Power Save Microchip TCP/IP Stack Help

11.7.4

Types

Module

702) tWFPwrModeReq ( see page 702)

Types

Name

tWFPsPwrMode ( see page

Description

Enumeration of valid values for WFSetPowerSaveMode()

This is type tWFPwrModeReq.

11.7.4.1

tWFPsPwrMode Type

File

WFPowerSave.c

C typedef enum

tWFPsPwrMode@1 tWFPsPwrMode;

Description

Enumeration of valid values for WFSetPowerSaveMode()

11.7.4.2

tWFPwrModeReq Type

File

WFPowerSave.c

C typedef struct

pwrModeRequestStruct tWFPwrModeReq;

Description

This is type tWFPwrModeReq.

11.7.5

Variables

Module

g_powerSaveState ( see page 703)

Variables

Name

Description

g_AppPowerSaveModeEnabled

( see page 703)

This is variable g_AppPowerSaveModeEnabled.

LOCAL GLOBAL VARIABLES

g_psPollActive ( see page

703) g_rxDtim ( see page 703)

This is variable g_psPollActive.

This is variable g_rxDtim.

Variables

702

11.7 Wi-Fi Power Save Microchip TCP/IP Stack Help

g_sleepNeeded ( see page

704) gRFModuleVer1209orLater ( see page 704)

This is variable g_sleepNeeded.

This is variable gRFModuleVer1209orLater.

11.7.5.1

g_AppPowerSaveModeEnabled Variable

File

WFPowerSave.c

BOOL g_AppPowerSaveModeEnabled = FALSE;

Description

This is variable g_AppPowerSaveModeEnabled.

11.7.5.2

g_powerSaveState Variable

File

WFPowerSave.c

UINT8 g_powerSaveState = WF_PS_OFF;

Description

LOCAL GLOBAL VARIABLES

11.7.5.3

g_psPollActive Variable

File

WFPowerSave.c

BOOL g_psPollActive = FALSE;

Description

This is variable g_psPollActive.

11.7.5.4

g_rxDtim Variable

File

WFPowerSave.c

BOOL g_rxDtim;

Description

This is variable g_rxDtim.

Variables

703

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help

11.7.5.5

g_sleepNeeded Variable

File

WFPowerSave.c

BOOL g_sleepNeeded = FALSE;

Description

This is variable g_sleepNeeded.

11.7.5.6

gRFModuleVer1209orLater Variable

File

WFPowerSave.c

BOOL gRFModuleVer1209orLater;

Description

This is variable gRFModuleVer1209orLater.

11.7.6

Macros

Macros

Name Description

REG_DISABLE_LOW_POWER_MASK

( see page 704)

This is macro REG_DISABLE_LOW_POWER_MASK.

Module

11.7.6.1

REG_DISABLE_LOW_POWER_MASK Macro

File

WFPowerSave.c

#define

REG_DISABLE_LOW_POWER_MASK ((UINT16)(0x00))

Description

This is macro REG_DISABLE_LOW_POWER_MASK.

704

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help

11.8

Wi-Fi Miscellaneous

Module

WF_GetDeviceInfo ( see page 706)

Description

Wi-Fi Miscellaneous Public Members

11.8.1

Wi-Fi Miscellaneous Public Members

Functions

Name

Description

Retrieves WF device information

(MRF24WB0M_DEVICE/MRF24WG0M_DEVICE, romVersion and patchVersion).

Retrieves the MRF24W MAC address

WF_GetMacAddress ( see page 706)

WF_GetMacStats ( see page 707)

WF_GetMultiCastFilter ( see page 707)

WF_GetRegionalDomain ( see page 708)

WF_GetRtsThreshold ( see page 709)

WF_SetMacAddress ( see page 710)

Gets MAC statistics.

Gets a multicast address filter from one of the two multicast filters.

Retrieves the MRF24W Regional domain

Gets the RTS Threshold

Uses a different MAC address for the MRF24W

WF_SetMultiCastFilter ( see page 710)

WF_SetRegionalDomain ( see page 711)

Sets a multicast address filter using one of the two multicast filters.

Enables or disables the MRF24W Regional Domain. For MRF24WG with RF module FW version 0x3106 or earlier, it allows enabling /disabling the Regional

Domain. For MRF24WG with RF module FW version 0x3107 and future releases, this function is NOT supported due to changes in FCC requirements, which does not allow programming of the regional domain.

WF_SetRtsThreshold ( see page 712)

Sets the RTS Threshold.

WF_EnableSWMultiCastFilter

( see page 714)

Forces the module FW to use software filter instead of hardware filter

WF_MulticastSetConfig ( see page 714)

Sets a multicast address filter using one of the two multicast filters.

WF_SetLinkDownThreshold

( see page 715)

WF_GetTxMode ( see page

716)

Can be called to set link down threshold in softAP network type.

Retrieves transmission (tx) mode that indicates transmission rates

WF_SetTxMode ( see page

716)

Configures 802.11 transmission (Tx) rates

Module

Wi-Fi Miscellaneous ( see page 705)

705

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

Structures

Name

tWFDeviceInfoStruct ( see page 712)

WFMacStatsStruct ( see page 713)

WFHibernate ( see page

716)

Description

used in WF_GetDeviceInfo ( see page 706)

This is record WFMacStatsStruct.

This is record WFHibernate.

Description

The following functions and variables are available to the stack application.

11.8.1.1

WF_GetDeviceInfo Function

File

WFApi.h

C void

WF_GetDeviceInfo(

tWFDeviceInfo * p_deviceInfo

);

Returns

None.

Description

Version functions

Retrieves RF module information. MRF24WB will have romVersion = 0x12. MRF24WG will have romVersion = 0x30 or 0x31.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_deviceInfo

Description

Pointer where device info will be written

11.8.1.2

WF_GetMacAddress Function

File

WFApi.h

C void

WF_GetMacAddress(

UINT8 * p_mac

);

Returns

None.

Remarks

None.

706

11.8 Wi-Fi Miscellaneous

Preconditions

MACInit must be called first.

Parameters

p_mac

Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

Description

Pointer where mac will be written (must point to a 6-byte buffer)

11.8.1.3

WF_GetMacStats Function

File

WFApi.h

C void

WF_GetMacStats(

tWFMacStats * p_macStats

);

Returns

None.

Description

MAC Stats

Returns MAC statistics on number of frames received or transmitted for defined situations such as number of frames transmitted with multicast bit set in destination MAC address. Refer to WFApi.h for data struct tWFMacStats.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_macStats

Description

Pointer to where MAC statistics are written

11.8.1.4

WF_GetMultiCastFilter Function

File

WFApi.h

C void

WF_GetMultiCastFilter(

UINT8 multicastFilterId,

UINT8 multicastAddress[6]

);

Returns

None.

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:

707

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

[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 ( see page 152) 0 address

[12] -- Compare Address ( see page 152) 0 group

[13] -- Compare Address ( see page 152) 0 type

[14-19] -- Compare Address ( see page 152) 1 address

[20] -- Compare Address ( see page 152) 1 group

[21] -- Compare Address ( see page 152) 1 type

[22-27] -- Compare Address ( see page 152) 2 address

[28] -- Compare Address ( see page 152) 2 group

[29] -- Compare Address ( see page 152) 2 type

[30-35] -- Compare Address ( see page 152) 3 address

[36] -- Compare Address ( see page 152) 3 group

[37] -- Compare Address ( see page 152) 3 type

[38-43] -- Compare Address ( see page 152) 4 address

[44] -- Compare Address ( see page 152) 4 group

[45] -- Compare Address ( see page 152) 4 type

[46-51] -- Compare Address ( see page 152) 5 address

[52] -- Compare Address ( see page 152) 5 group

[53] -- Compare Address ( see page 152) 5 type

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

multicastFilterId multicastAddress

Description

WF_MULTICAST_FILTER_1 or WF_MULTICAST_FILTER_2

6-byte address

11.8.1.5

WF_GetRegionalDomain Function

File

WFApi.h

C void

WF_GetRegionalDomain(

UINT8 * p_regionalDomain

);

708

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

Returns

None.

Description

see tWFRegDomain enumerated types

Gets the regional domain on the MRF24W. Allowable values are:

• WF_DOMAIN_FCC

• WF_DOMAIN_IC (MRF24WB)

• WF_DOMAIN_ETSI

• WF_DOMAIN_SPAIN (MRF24WB)

• WF_DOMAIN_FRANCE (MRF24WB)

• WF_DOMAIN_JAPAN_A (MRF24WB)

• WF_DOMAIN_JAPAN_B (MRF24WB)

• WF_DOMAIN_JAPAN (MRF24WG)

• WF_DOMAIN_OTHER (MRF24WG)

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_regionalDomain

Description

Pointer where the regional domain value will be written

11.8.1.6

WF_GetRtsThreshold Function

File

WFApi.h

C void

WF_GetRtsThreshold(

UINT16 * p_rtsThreshold

);

Returns

None.

Description

Gets the RTS/CTS packet size threshold.

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

p_rtsThreshold

Description

Pointer to where RTS threshold is written

709

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

11.8.1.7

WF_SetMacAddress Function

File

WFApi.h

C void

WF_SetMacAddress(

UINT8 * p_mac

);

Returns

None.

Description

MAC Address ( see page 152) Functions

Directs the MRF24W to use the input MAC address instead of its factory-default MAC address. This function does not overwrite the factory default, which is in FLASH memory – it simply tells the MRF24W to use a different MAC.

Remarks

None.

Preconditions

MACInit must be called first. Cannot be called when the MRF24W is in a connected state.

Parameters

p_mac

Description

Pointer to 6-byte MAC that will be sent to MRF24W

11.8.1.8

WF_SetMultiCastFilter Function

File

WFApi.h

C void

WF_SetMultiCastFilter(

UINT8 multicastFilterId,

UINT8 multicastAddress[6]

);

Returns

None.

Description

Multicast Functions

This function allows the application to configure up to two Multicast Address ( see page 152) 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.

Remarks

None.

710

11.8 Wi-Fi Miscellaneous

Preconditions

MACInit must be called first.

Parameters

multicastFilterId multicastAddress

Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

Description

WF_MULTICAST_FILTER_1 or WF_MULTICAST_FILTER_2

6-byte address (all 0xFF will inactivate the filter)

11.8.1.9

WF_SetRegionalDomain Function

File

WFApi.h

C void

WF_SetRegionalDomain(

UINT8 regionalDomain

);

Returns

None.

Description

see tWFRegDomain enumerated types

(MRF24WG 0x3106 or earlier ) Sets the regional domain on the MRF24WG. Note that this function does not overwrite the factory-set regional domain in FLASH. By default the MRF24W will use the factory-set regional domain. It is invalid to call this function while in a connected state. (MRF24WG 0x3107 and future) Not supported.

Valid values for the regional domain are:

• WF_DOMAIN_FCC

• WF_DOMAIN_IC (MRF24WB)

• WF_DOMAIN_ETSI

• WF_DOMAIN_SPAIN (MRF24WB)

• WF_DOMAIN_FRANCE (MRF24WB)

• WF_DOMAIN_JAPAN_A (MRF24WB)

• WF_DOMAIN_JAPAN_B (MRF24WB)

• WF_DOMAIN_JAPAN (MRF24WG)

• WF_DOMAIN_OTHER (MRF24WG)

Remarks

None.

Preconditions

MACInit must be called first. This function must not be called while in a connected state.

Parameters

regionalDomain

Description

Value to set the regional domain to

711

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

11.8.1.10

WF_SetRtsThreshold Function

File

WFApi.h

C void

WF_SetRtsThreshold(

UINT16 rtsThreshold

);

Returns

None.

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

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

rtsThreshold

Description

Value of the packet size threshold

11.8.1.11

tWFDeviceInfoStruct Structure

File

WFApi.h

C struct

tWFDeviceInfoStruct {

UINT8 deviceType;

UINT8 romVersion;

UINT8 patchVersion;

};

Members

UINT8 deviceType;

UINT8 romVersion;

UINT8 patchVersion;

Description

used in WF_GetDeviceInfo ( see page 706)

Description

MRF24WB0M_DEVICE or MRF24WG0M_DEVICE

ROM version number

Patch version number

712

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

11.8.1.12

WFMacStatsStruct Structure

File

WFApi.h

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;

};

Members

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

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.

Total number of Tx bytes that have been transmitted

Number of frames successfully transmitted that had the multicast bit set in the destination MAC address.

Number of Tx frames that failed due to the number of transmits exceeding the retry count.

Number of times a transmitted frame needed to be retried

Number of times a frame was successfully transmitted after more than one retransmission.

Number of Tx frames successfully transmitted.

Number of frames received where the Sequence Control field indicates a duplicate.

Number of CTS frames received in response to an RTS frame.

Number of times an RTS frame was not received in response to a CTS frame.

Number of times an Ack was not received in response to a Tx frame.

Total number of Rx bytes received.

Number of successful received frames (management or data)

Number of frames received with the multicast bit set in the destination MAC address.

Number of frames received with an invalid Frame Checksum (FCS).

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.

Number of times that fragments ‘aged out’, or were not received in the allowable time.

Number of MIC failures that have occurred.

713

11.8 Wi-Fi Miscellaneous

Description

This is record WFMacStatsStruct.

Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

11.8.1.13

WF_EnableSWMultiCastFilter Function

File

WFApi.h

C void

WF_EnableSWMultiCastFilter();

Returns

None.

Description

This function allows the application to configure up to max 16 Multicast Address ( see page 152) Filters on the

MRF24WG0MA/B.

Remarks

None.

Preconditions

MACInit must be called first.

11.8.1.14

WF_MulticastSetConfig Function

File

WFApi.h

C void

WF_MulticastSetConfig(

tWFMultiCastConfig * p_config

);

Returns

None.

Description

This function allows the application to configure up to two Multicast Address ( see page 152) Filters on the MRF24W. If two

active multicast filters are set up they are OR’d together – the MRF24W will receive and pass to the Host CPU received packets from either multicast address. The allowable values in p_config are: filterId -- WF_MULTICAST_FILTER_1 or WF_MULTICAST_FILTER_2 action -- WF_MULTICAST_DISABLE_ALL (default) The Multicast Filter discards all received multicast messages – they will not be forwarded to the Host PIC. The remaining fields in this structure are ignored.

WF_MULTICAST_ENABLE_ALL The Multicast Filter forwards all received multicast messages to the Host PIC. The remaining fields in this structure are ignored.

WF_MULTICAST_USE_FILTERS The MAC filter will be used and the remaining fields in this structure configure which

Multicast messages are forwarded to the Host PIC.

macBytes -- Array containing the MAC address to filter on (using the destination address of each incoming 802.11 frame).

Specific bytes with the MAC address can be designated as ‘don’t care’ bytes. See macBitMask. This field in only used if action = WF_MULTICAST_USE_FILTERS.

714

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members macBitMask -- A byte where bits 5:0 correspond to macBytes[5:0]. If the bit is zero then the corresponding MAC byte must be an exact match for the frame to be forwarded to the Host PIC. If the bit is one then the corresponding MAC byte is a ‘don’t care’ and not used in the Multicast filtering process. This field in only used if action = WF_MULTICAST_USE_FILTERS.

By default, both Multicast Filters are inactive.

Remarks

None.

Preconditions

MACInit must be called first.

Example

- Filter on Multicast Address of 01:00:5e:xx:xx:xx where xx are don't care bytes.

p_config->filterId = WF_MULTICAST_FILTER_1

[0] [1] [2] [3] [4] [5] p_config->macBytes[] = 01, 00, 5e, ff, ff, ff (0xff are the don't care bytes) p_config->macBitMask = 0x38 --> bits 5:3 = 1 (don't care on bytes 3,4,5)

--> bits 2:0 = 0 (exact match required on bytes 0,1,2)

11.8.1.15

WF_SetLinkDownThreshold Function

File

WFApi.h

C void

WF_SetLinkDownThreshold(

UINT8 threshold

);

Returns

None.

Description

When MRF24W is configured as a softAP, it will ping the devices to determine whether devices are alive or dead by transmitting consecutive NULL DATA packets. If device is alive, it will transmit ACK back to softAP. If device is dead, softAP will not receive any packets from device. After PARAM_LINK_DOWN_THRESHOLD is reached, softAP considers the device to be dead. To enable this feature, enable SOFTAP_CHECK_LINK_STATUS. This function is only valid with MRF24WG RF module FW version 0x3107 or the later.

Remarks

None.

Preconditions

MACInit must be called first. SOFTAP_CHECK_LINK_STATUS must be enabled.

715

11.8 Wi-Fi Miscellaneous Microchip TCP/IP Stack Help Wi-Fi Miscellaneous Public Members

11.8.1.16

WF_GetTxMode Function

File

WFApi.h

C void

WF_GetTxMode(

UINT8 * mode

);

Returns

None.

Description

Retrieves transmission (tx) mode that indicates transmission rates (802.11b or 802.11g or 802.11 legacy rates)

Remarks

None.

Preconditions

MACInit must be called first.

11.8.1.17

WF_SetTxMode Function

File

WFApi.h

C void

WF_SetTxMode(

UINT8 mode

);

Returns

None.

Description

Configures 802.11 transmission (Tx) rates for 802.11b or 802.11g or 802.11 legacy rates (1-2Mbps)

Remarks

None.

Preconditions

MACInit must be called first.

Parameters

mode

Description

Tx rate WF_TXMODE_G_RATES (default) -- will use all 802.11g rates

WF_TXMODE_B_RATES -- will only use 802.11b rates

WF_TXMODE_LEGACY_RATES -- will only use 1 and 2 mbps rates

11.8.1.18

WFHibernate Structure

File

WFApi.h

716

Microchip TCP/IP Stack Help 11.9 WF_ProcessEvent

C struct

WFHibernate {

UINT8 state;

UINT8 wakeup_notice;

};

Description

This is record WFHibernate.

11.9

WF_ProcessEvent

Module

1. Bit mask eventNotificationAction in the tWFCAElements structure (see Wi-Fi Connection Algorithm ( see page 652)), or

Description

There are several events that can occur on the MRF24WB0M / MRF24WG0M that the host CPU may want to know about.

All MRF24WB0M / MRF24WG0M 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_Config.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 WF_ProcessEvent(). 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: void WF_ProcessEvent(UINT8 event, UINT16 eventInfo, UINT8 *extraInfo)

There are 3 inputs to the function: event eventInfo

*extraInfo

The event that occurred.

Additional information about the event. Not all events have associated info, in which case this value will be set to WF_NO_ADDITIONAL_INFO (0xff)

Additional information about the event. When DERIVE_KEY_FROM_PASSPHRASE_IN_HOST is enabled. where host will compute the key from the passphrade, this field contains the WPA

Passphrase that will be sent to the host for the computation.

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:

2. Function WF_CASetEventNotificationAction() ( see page 665).

event

WF_EVENT_CONNECTION_SUCCESSFUL

eventInfo

The connection attempt was successful.

eventInfo:

• Always

WF_NO_ADDITIONAL_INFO

(Optional event)

717

11.9 WF_ProcessEvent Microchip TCP/IP Stack Help

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 ( see page 678)()

is called, in which case the eventInfo field has no meaning.

WF_EVENT_CONNECTION_REESTABLISHED

WF_EVENT_SCAN_RESULTS_READY

WF_EVENT_SOFT_AP_EVENT

(Optional event)

A connection that was temporarily lost has been restablished

Always WF_NO_ADDITIONAL_INFO

(Optional event)

The scan request initiated by calling

WF_Scan ( see page 680)()

has completed and results can be read from the MRF24WB0M /

MRF24WG0M.

eventInfo: Number of scan results

Available only for MRF24WG0M (i) RF module FW version 0x3108 and later and (ii) MLA v5.42.06 release or later. Indication of client's connection status, when a client has connected or disconnected or not powered on/active or received deauthentication.

718

11.10 Access Point Compatibility Microchip TCP/IP Stack Help

WF_EVENT_KEY_CALCULATION_REQUEST This event is generated

DERIVE_KEY_FROM_PASSPHRASE_IN_HOST is

when

enabled,

MRF24WG0M will transmit the passphase to the host via the field

*extraInfo. where the host will then compute the passphrase from the

key. Refer to function prototype WF_ConvPassphrase2Key ( see page

687)() for more information.

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.

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_CONNECTION_REESTABLISHED:

/* Application code here */

break

;

case

WF_EVENT_SCAN_RESULTS_READY:

/* Application code here */

break

;

default

WF_ASSERT(FALSE);

break

;

}

11.10

Access Point Compatibility

Module

Description

Introduction

The MRF24WB0M / MRF24WG0M 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 section 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.

719

11.10 Access Point Compatibility Microchip TCP/IP Stack Help

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

• Apple Airport Express

• Apple Airport Extreme

• Apple Time Capsule

• Asus RT-N16

• Asus WL530g

720

11.10 Access Point Compatibility

• AirLink AR690W

• Belkin N1

• Belkin F5D7231-4

• Belkin F5D8231-4

• Belkin F7D1301 v1

• Belkin F7D3302 v1

• Belkin F7D5301 v1

• Belkin Surf N300

• Buffalo WHR-G125

• Buffalo WHR-HP-G54

• Buffalo WHR-HP-GN

• Cisco E1000

• Cisco E3000

• Cisco E4200

• Cisco M20

• Cisco Vallet M10

• Corega CG-WLAPGMN

• Corega CG-WLBARGO

• D-Link DI-524

• D-Link DIR-615

• D-Link DIR-655

• D-Link DIR-665

• D-Link DIR-825

• D-Link DIR-855

• D-Link WBR-1310

• D-Link WBR-2310

• Dynex DX-WGRTR G

• Dynex DX-WGRTR v1000

• Level1 WBR-3408

• Linksys WRT150N v1.1

• Linksys WRT310N

• Linksys WRT54G2

• Microsoft MN-700

• Netgear WG103

• Netgear WGR614v9

• Netgear WGT624v2

• Netgear WN2000RPT

• Netgear WN802T v2

• Netgear WNDR3300

• Netgear WNDR3700

• Netgear WNR1000 v2

• Netgear WNR1000 v3

Microchip TCP/IP Stack Help

721

11.11 802.11 AP/Router Configuration

• Netgear WNR200 v3

• Netgear WPN824v2

• Netgear WNR854T

• PCI MZK-W04NU

• Proxim AP-700

• SMC Networks SMCWBR14S-N4

• SMC Networks SMCWBR14T-G

• TP-Link TL-WR340G

• TP-Link TL-WR541G

• TP-Link TL-WR740N

• TP-Link TL-WR741ND

• TP-Link TL-WR841ND

• TP-Link TL-WR941N/D

• Westell B90-327W15-06

• ZyXel P-330W

• ZyXel X550N

*Note Tests Performed:

• Basic association with the AP (no security)

• Association with WEP security

• Association with WPA/WPA2-PSK security

• Ping test validation.

Microchip TCP/IP Stack Help

11.11

802.11 AP/Router Configuration Settings

Module

Description

Tips for Setting up Routers for 802.11b/g Use

The purpose of this section is to describe the settings for the most typical AP configurable parameters to enable compatibility with the Microchip MRF24WB0M / MRF24WG0M 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.

722

11.12 WiFi Troubleshooting Tips Microchip TCP/IP Stack Help Read back RF module FW version

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 / MRF24WG0M, 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.

11.12

WiFi Troubleshooting Tips

Module