Jan 5, 2010 ... Implementing applications with wireless networking is now common. ... to the
Microchip application note AN1283 “Microchip Wireless Media.
David Flowers and Yifeng Yang. Microchip Technology Inc. Microchip MiWi⢠Wireless ...... Farmington Hills, MI. Tel: 24
MOTOR SPECIFICATION SHEET. BRUSHLESS DC MOTOR FAMILY. Series NT
DYNAMO® Brushless DC Permanent Magnet Motor ... Affordable Servo Control.
FTP Client mode App Note www.rovingnetworks.com. Version 1.0 12/23/2010.
809 University Avenue • Los Gatos, CA 95032 • Tel (408) 395-6539 ...
including Microsoft, Apple, and Mozilla are improving in- built support in their products to send stack traces back to developers when the software crashes.
data to be sent over SpaceWire using standard network protocols such as .... A SpaceWire router [13] was added to the network for one test, to measure the ...
There was a problem previewing this document. Retrying... Download. Connect more apps... Try one of the apps below to op
1 Ene 2009 ... Introducción. Jos. Microchip PIC. 2. Microcontroladores. Introducción: Por cada
procesador de propósito general vendido, se venden más de ...
0.10 C. Microchip Technology Drawing No. C04-057-Atmel Rev D Sheet 1 of 2. 8X. For the most current package drawings, pl
Ming Xing Financial Tower. No. 88 TIDU Street. Chengdu 610016, China. Tel: 86-28-86766200 Fax: 86-28-86766599. China - F
PDF Pro MERN Stack: Full Stack Web App Development with Mongo, Express, React, and Node, PDF online, PDF new Pro MERN St
PDF Download Pro MERN Stack: Full Stack Web App Development with Mongo, ... Development with Mongo, Express, React, and
Assemble the complete stack required to build a modern web app using React: MongoDB (a ... Facebook s React is a technol
PDF Pro MERN Stack: Full Stack Web App Development with Mongo, Express, React, and Node, PDF online, PDF new Pro MERN St
PDF Download Pro MERN Stack: Full Stack Web App Development with Mongo, Express, React, and .... View-Controller (MVC) a
Web App Development with Mongo, Express,. React, and Node Full Audiobook .... too prescriptive by being a framework.Face
PDF Download Pro MERN Stack: Full Stack Web App Development with Mongo, Express, React, and Node, All Ebook Downloads Pr
Online PDF Pro MERN Stack: Full Stack Web App Development with Mongo, Express, .... NoSQL database) and Express (a frame
Web App Development with Mongo, Express, React, and Node Download Online, ..... other tools that go into building a comp
Online PDF Pro MERN Stack: Full Stack Web App Development with Mongo, .... other tools that go into building a complete
Web App Development with Mongo, Express, React, and Node, free download ... Express, React, and Node, Download Best Book
Assemble the complete stack required to build a modern web app using React: MongoDB (a NoSQL database) and. Express (a f
NoSQL database) and Express (a framework for web application servers), which runs on Node. (JavaScript on the server sid
Related Book PDF Book Pro Mern Stack Full Stack Web App Development .... app using React: MongoDB (a NoSQL database) and
Microchip TCP/IP Stack Help _SNMPSetTxOffset Macro
334
AGENT_NOTIFY_PORT Macro
334
appendZeroToOID Variable
334
ASN_INT Macro
334
ASN_NULL Macro
335
ASN_OID Macro
335
DATA_TYPE Enumeration
335
DATA_TYPE_INFO Structure
336
DATA_TYPE_TABLE_SIZE Macro
336
dataTypeTable Variable
336
FindOIDsInRequest Function
337
GET_BULK_REQUEST Macro
337
GET_NEXT_REQUEST Macro
337
GET_REQUEST Macro
337
GET_RESPONSE Macro
337
hMPFS Variable
338
INDEX_INFO Union
338
IS_AGENT_PDU Macro
338
IS_ASN_INT Macro
339
IS_ASN_NULL Macro
339
IS_GET_NEXT_REQUEST Macro
339
IS_GET_REQUEST Macro
339
IS_GET_RESPONSE Macro
339
IS_OCTET_STRING Macro
340
IS_OID Macro
340
GetDataTypeInfo Function
340
IS_SET_REQUEST Macro
340
IS_STRUCTURE Macro
341
IS_TRAP Macro
341
IsASNNull Function
341
MIB_INFO Union
341
OCTET_STRING Macro
342
OID_INFO Structure
342
PDU_INFO Structure
343
reqVarErrStatus Structure
343
SET_REQUEST Macro
344
SetErrorStatus Function
344
SNMP_AGENT_PORT Macro
344
SNMP_BIB_FILE_NAME Macro
345
SNMP_COUNTER32 Macro
345
SNMP_ERR_STATUS Enumeration
345
SNMP_GAUGE32 Macro
346 xiv
Microchip TCP/IP Stack Help SNMP_IP_ADDR Macro
346
SNMP_NMS_PORT Macro
347
SNMP_NOTIFY_INFO Structure
347
SNMP_NSAP_ADDR Macro
347
IsValidLength Function
348
SNMP_OPAQUE Macro
348
SNMP_STATUS Union
348
SNMP_TIME_TICKS Macro
348
SNMP_V1 Macro
349
SNMP_V2C Macro
349
SNMPAgentSocket Variable
349
SNMPNotifyInfo Variable
349
snmpReqVarErrStatus Variable
350
SNMPRxOffset Variable
350
SNMPStatus Variable
350
SNMPTxOffset Variable
350
STRUCTURE Macro
350
TRAP Macro
351
trapInfo Variable
351
GetDataTypeInfo Function
351
GetNextLeaf Function
351
GetOIDStringByAddr Function
352
GetOIDStringByID Function
352
IsValidCommunity Function
352
IsValidInt Function
352
IsValidLength Function
353
IsValidOID Function
353
IsValidPDU Function
353
IsValidStructure Function
353
OIDLookup Function
354
ProcessGetSetHeader Function
354
ProcessHeader Function
355
ProcessSetVar Function
355
ProcessVariables Function
355
ReadMIBRecord Function
356
SNMPCheckIfPvtMibObjRequested Function
356
Stack Members
357
SNMPInit Function
357
SNMPTask Function
357
Functions
358
getSnmpV2GenTrapOid Function
359
ProcessGetBulkVar Function
359 xv
Microchip TCP/IP Stack Help ProcessGetNextVar Function
360
ProcessGetVar Function
360
ProcessSnmpv3MsgData Function
360
SNMPGetExactIndex Function
360
SNMPIdRecrdValidation Function
361
SNMPIsValidSetLen Function
362
Snmpv3AESDecryptRxedScopedPdu Function
362
Snmpv3BufferPut Function
362
Snmpv3FormulateEngineID Function
363
Snmpv3GetAuthEngineTime Function
363
Snmpv3GetBufferData Function
363
Snmpv3InitializeUserDataBase Function
363
Snmpv3MsgProcessingModelProcessPDU Function
364
Snmpv3Notify Function
364
Snmpv3ScopedPduProcessing Function
364
Snmpv3TrapScopedpdu Function
364
Snmpv3UserSecurityModelProcessPDU Function
365
Snmpv3UsmAesEncryptDecryptInitVector Function
365
Snmpv3UsmOutMsgAuthenticationParam Function
365
Snmpv3ValidateEngineId Function
365
Snmpv3ValidateSecNameAndSecLvl Function
366
Snmpv3ValidateSecurityName Function
366
Types
366
INOUT_SNMP_PDU Enumeration
366
SNMPNONMIBRECDINFO Structure
367
SNMPV3MSGDATA Structure
367
Variables
367
getZeroInstance Variable
368
gSNMPv3ScopedPduDataPos Variable
368
gSNMPv3ScopedPduRequestBuf Variable
368
gSNMPv3ScopedPduResponseBuf Variable
368
msgSecrtyParamLenOffset Variable
369
Macros
369
IS_SNMPV3_AUTH_STRUCTURE Macro
369
REPORT_RESPONSE Macro
369
SNMP_MAX_MSG_SIZE Macro
370
SNMP_V3 Macro
370
SNTP Client Public Members SNTPGetUTCSeconds Function Stack Members SNTPClient Function
370 370 371 371 371 xvi
Microchip TCP/IP Stack Help Internal Members
372
NTP_PACKET Structure
372
dwLastUpdateTick Variable
373
dwSNTPSeconds Variable
374
NTP_EPOCH Macro
374
NTP_FAST_QUERY_INTERVAL Macro
374
NTP_QUERY_INTERVAL Macro
374
NTP_REPLY_TIMEOUT Macro
375
NTP_SERVER Macro
375
NTP_SERVER_PORT Macro
375
SSL
375
Generating Server Certificates
377
Public Members
380
SSL_INVALID_ID Macro
380
TCPAddSSLListener Function
381
TCPSSLIsHandshaking Function
381
TCPStartSSLClient Function
382
TCPIsSSL Function
382
SSLStartSession Function
383
SSL_SUPPLEMENTARY_DATA_TYPES Enumeration
383
SSL_PKEY_INFO Structure
383
SSL_RSA_KEY_SIZE Macro
384
SSL_RSA_CLIENT_SIZE Macro
384
Stack Members
384
SSL_STATE Enumeration
385
SSLInit Function
386
SSLPeriodic Function
386
TCPRequestSSLMessage Function
386
TCPSSLGetPendingTxSize Function
387
TCPSSLHandleIncoming Function
387
TCPSSLHandshakeComplete Function
388
TCPSSLInPlaceMACEncrypt Function
388
TCPSSLPutRecordHeader Function
389
TCPStartSSLServer Function
390
SSL_MIN_SESSION_LIFETIME Macro
390
SSL_RSA_LIFETIME_EXTENSION Macro
390
Internal Members
391
CalculateFinishedHash Function
396
GenerateHashRounds Function
396
GenerateSessionKeys Function
397
HSEnd Function
397
HSGet Function
398 xvii
Microchip TCP/IP Stack Help HSGetArray Function
398
HSGetWord Function
399
HSPut Function
399
HSPutArray Function
400
HSPutROMArray Function
401
HSPutWord Function
401
HSStart Function
401
isBufferUsed Variable
402
isHashUsed Variable
402
isStubUsed Variable
402
masks Variable
403
ptrHS Variable
403
RESERVED_SSL_MEMORY Macro
403
LoadOffChip Function
403
SaveOffChip Function
404
SM_SSL_RX_SERVER_HELLO Enumeration
404
SSL_ALERT Macro
405
SSL_ALERT_LEVEL Enumeration
405
SSL_APPLICATION Macro
405
SSL_BASE_BUFFER_ADDR Macro
406
SSL_BASE_HASH_ADDR Macro
406
SSL_BASE_KEYS_ADDR Macro
406
SSL_BASE_SESSION_ADDR Macro
406
SSL_BASE_STUB_ADDR Macro
406
SSL_BUFFER Union
407
SSL_BUFFER_SIZE Macro
407
SSL_BUFFER_SPACE Macro
407
SSL_CERT Variable
408
SSL_CERT_LEN Variable
408
SSL_CHANGE_CIPHER_SPEC Macro
408
SSL_HANDSHAKE Macro
408
SSL_HASH_SIZE Macro
408
SSL_HASH_SPACE Macro
409
SSL_KEYS Structure
409
SSL_KEYS_SIZE Macro
410
SSL_KEYS_SPACE Macro
410
SSL_MESSAGES Enumeration
410
SSL_RSA_EXPORT_WITH_ARCFOUR_40_MD5 Macro
411
SSL_RSA_WITH_ARCFOUR_128_MD5 Macro
411
SSL_SESSION Structure
411
SSL_SESSION_SIZE Macro
412
SSL_SESSION_SPACE Macro
412 xviii
Microchip TCP/IP Stack Help SSL_SESSION_STUB Structure
412
SSL_SESSION_TYPE Enumeration
413
SSL_STUB Structure
413
SSL_STUB_SIZE Macro
414
SSL_STUB_SPACE Macro
414
SSL_VERSION Macro
415
SSL_VERSION_HI Macro
415
SSL_VERSION_LO Macro
415
SSLBufferAlloc Function
415
SSLBufferFree Function
416
sslBufferID Variable
416
SSLBufferSync Function
417
SSLFinishPartialRecord Macro
417
SSLFlushPartialRecord Macro
417
sslHash Variable
418
SSLHashAlloc Function
418
SSLHashFree Function
418
sslHashID Variable
419
SSLHashSync Function
419
sslKeys Variable
420
sslKeysID Variable
420
SSLKeysSync Function
420
SSLMACAdd Function
421
SSLMACBegin Function
421
SSLMACCalc Function
421
SSLRSAOperation Function
421
sslRSAStubID Variable
422
SSLRxAlert Function
422
SSLRxAntiqueClientHello Function
423
SSLRxCCS Function
423
SSLRxClientHello Function
424
SSLRxClientKeyExchange Function
424
SSLRxFinished Function
425
SSLRxHandshake Function
425
SSLRxRecord Function
426
SSLRxServerCertificate Function
426
SSLRxServerHello Function
427
sslSession Variable
427
sslSessionID Variable
428
SSLSessionMatchID Function
428
SSLSessionMatchIP Function
428
SSLSessionNew Function
429 xix
Microchip TCP/IP Stack Help sslSessionStubs Variable
429
SSLSessionSync Function
430
SSLSessionUpdated Macro
430
sslSessionUpdated Variable
430
SSLStartPartialRecord Function
431
sslStub Variable
431
SSLStubAlloc Function
432
SSLStubFree Function
432
sslStubID Variable
433
SSLStubSync Function
433
SSLTerminate Function
433
SSLTxCCSFin Function
434
SSLTxClientHello Function
434
SSLTxClientKeyExchange Function
435
SSLTxMessage Function
435
SSLTxRecord Function
436
SSLTxServerCertificate Function
436
SSLTxServerHello Function
437
SSLTxServerHelloDone Function
438
Files SSLClientSize.h TCP
438 438 439
Public Members
440
INVALID_SOCKET Macro
442
UNKNOWN_SOCKET Macro
442
TCP_ADJUST_GIVE_REST_TO_RX Macro
442
TCP_ADJUST_GIVE_REST_TO_TX Macro
442
TCP_ADJUST_PRESERVE_RX Macro
442
TCP_ADJUST_PRESERVE_TX Macro
443
TCP_OPEN_IP_ADDRESS Macro
443
TCP_OPEN_NODE_INFO Macro
443
TCP_OPEN_RAM_HOST Macro
443
TCP_OPEN_ROM_HOST Macro
444
TCP_OPEN_SERVER Macro
444
TCPAdjustFIFOSize Function
444
TCPConnect Macro
445
TCPClose Function
445
TCPDiscard Function
446
TCPDisconnect Function
446
TCPFind Macro
447
TCPFindArray Macro
447
TCPFindArrayEx Function
447 xx
Microchip TCP/IP Stack Help TCPFindEx Function
448
TCPFindROMArray Macro
449
TCPFindROMArrayEx Function
449
TCPFlush Function
450
TCPGet Function
450
TCPGetArray Function
451
TCPGetRemoteInfo Function
451
TCPGetRxFIFOFree Function
452
TCPGetRxFIFOFull Macro
452
TCPGetTxFIFOFree Macro
453
TCPGetTxFIFOFull Function
453
TCPIsConnected Function
453
TCPIsGetReady Function
454
TCPIsPutReady Function
454
TCPListen Macro
455
TCPOpen Function
455
TCPPeek Function
457
TCPPeekArray Function
457
TCPPut Function
458
TCPPutArray Function
458
TCPPutROMArray Function
459
TCPPutROMString Function
459
TCPPutString Function
460
TCPRAMCopy Function
460
TCPRAMCopyROM Function
461
TCPWasReset Function
462
Stack Members
462
SOCKET_INFO Structure
463
TCB Structure
464
TCB_STUB Structure
465
TCP_SOCKET Type
466
TCP_STATE Enumeration
466
TCPInit Function
467
TCPProcess Function
468
TCPTick Function
468
TCPSSLDecryptMAC Function
469
TCPStartSSLClientEx Function
469
Internal Members
470
ACK Macro
472
CloseSocket Function
472
FIN Macro
472
FindMatchingSocket Function
473 xxi
Microchip TCP/IP Stack Help HandleTCPSeg Function
473
hCurrentTCP Variable
474
LOCAL_PORT_END_NUMBER Macro
474
LOCAL_PORT_START_NUMBER Macro
474
MyTCB Variable
474
MyTCBStub Variable
475
PSH Macro
475
RST Macro
475
SendTCP Function
475
SENDTCP_KEEP_ALIVE Macro
476
SENDTCP_RESET_TIMERS Macro
476
SwapTCPHeader Function
476
SYN Macro
477
SyncTCB Function
477
SyncTCBStub Macro
477
SYNQueue Variable
477
TCBStubs Variable
477
TCP_AUTO_TRANSMIT_TIMEOUT_VAL Macro
478
TCP_WINDOW_UPDATE_TIMEOUT_VAL Macro
478
TCP_CLOSE_WAIT_TIMEOUT Macro
478
TCP_DELAYED_ACK_TIMEOUT Macro
478
TCP_FIN_WAIT_2_TIMEOUT Macro
479
TCP_HEADER Structure
479
TCP_KEEP_ALIVE_TIMEOUT Macro
480
TCP_MAX_RETRIES Macro
480
TCP_MAX_SEG_SIZE_RX Macro
480
TCP_MAX_SEG_SIZE_TX Macro
481
TCP_MAX_SYN_RETRIES Macro
481
TCP_MAX_UNACKED_KEEP_ALIVES Macro
481
TCP_OPTIMIZE_FOR_SIZE Macro
481
TCP_OPTIONS Structure
482
TCP_OPTIONS_END_OF_LIST Macro
482
TCP_OPTIONS_MAX_SEG_SIZE Macro
482
TCP_OPTIONS_NO_OP Macro
482
TCP_SOCKET_COUNT Macro
483
TCP_START_TIMEOUT_VAL Macro
483
TCP_SYN_QUEUE Structure
483
TCP_SYN_QUEUE_MAX_ENTRIES Macro
484
TCP_SYN_QUEUE_TIMEOUT Macro
484
URG Macro
484
Variables NextPort Variable
484 484 xxii
Microchip TCP/IP Stack Help
TFTP
489
Public Members
490
TFTPClose Macro
492
TFTPCloseFile Function
492
TFTPGet Function
493
TFTPGetError Macro
493
TFTPIsFileClosed Function
494
TFTPIsFileOpened Function
494
TFTPIsFileOpenReady Macro
495
TFTPIsGetReady Function
495
TFTPIsOpened Function
496
TFTPIsPutReady Function
496
TFTPOpen Function
497
TFTPOpenFile Function
498
TFTPOpenROMFile Function
498
TFTPPut Function
499
TFTP_ACCESS_ERROR Enumeration
499
TFTP_FILE_MODE Enumeration
499
TFTP_RESULT Enumeration
500
TFTPGetUploadStatus Function
500
TFTPUploadFragmentedRAMFileToHost Function
501
TFTPUploadRAMFileToHost Function
502
TFTP_CHUNK_DESCRIPTOR Structure
502
TFTP_UPLOAD_COMPLETE Macro
503
TFTP_UPLOAD_CONNECT Macro
503
TFTP_UPLOAD_CONNECT_TIMEOUT Macro
503
TFTP_UPLOAD_GET_DNS Macro
503
TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT Macro
504
TFTP_UPLOAD_RESOLVE_HOST Macro
504
TFTP_UPLOAD_SEND_DATA Macro
504
TFTP_UPLOAD_SEND_FILENAME Macro
504
TFTP_UPLOAD_SERVER_ERROR Macro
504
TFTP_UPLOAD_WAIT_FOR_CLOSURE Macro
505
Stack Members
505
TFTP_ARP_TIMEOUT_VAL Macro
505
TFTP_GET_TIMEOUT_VAL Macro
506
TFTP_MAX_RETRIES Macro
506
Internal Members
506
MutExVar Variable
507
TFTP_BLOCK_SIZE Macro
508
TFTP_BLOCK_SIZE_MSB Macro
508
TFTP_CLIENT_PORT Macro
508 xxiii
Microchip TCP/IP Stack Help TFTP_OPCODE Enumeration
508
TFTP_SERVER_PORT Macro
509
TFTP_STATE Enumeration
509
_tftpError Variable
509
_tftpFlags Variable
509
_tftpRetries Variable
510
_TFTPSendAck Function
510
_TFTPSendFileName Function
510
_TFTPSendROMFileName Function
511
_tftpSocket Variable
511
_tftpStartTick Variable
511
_tftpState Variable
511
smUpload Variable
511
uploadChunkDescriptor Variable
512
uploadChunkDescriptorForRetransmit Variable
512
vUploadFilename Variable
512
vUploadRemoteHost Variable
512
wUploadChunkOffset Variable
513
wUploadChunkOffsetForRetransmit Variable
513
Tick
513
Public Members
514
TICK Type
514
TICK_HOUR Macro
515
TICK_MINUTE Macro
515
TICK_SECOND Macro
515
TickConvertToMilliseconds Function
515
TickGet Function
516
TickGetDiv256 Function
516
TickGetDiv64K Function
517
Stack Functions
517
TickInit Function
517
TickUpdate Function
518
Internal Members
518
dwInternalTicks Variable
518
GetTickCopy Function
519
TICKS_PER_SECOND Macro
519
vTickReading Variable
519
UDP
520
Public Members
521
INVALID_UDP_PORT Macro
522
INVALID_UDP_SOCKET Macro
522
xxiv
Microchip TCP/IP Stack Help UDP_SOCKET Type
522
UDPOpenEx Function
523
UDPOpen Macro
524
UDPClose Function
525
UDPDiscard Function
525
UDPFlush Function
526
UDPGet Function
526
UDPGetArray Function
527
UDPIsGetReady Function
527
UDPIsPutReady Function
528
UDPPut Function
528
UDPPutArray Function
529
UDPPutROMArray Function
529
UDPPutROMString Function
530
UDPPutString Function
530
UDPSetRxBuffer Function
531
UDPSetTxBuffer Function
531
UDPIsOpened Function
532
UDP_OPEN_IP_ADDRESS Macro
532
UDP_OPEN_NODE_INFO Macro
532
UDP_OPEN_RAM_HOST Macro
533
UDP_OPEN_ROM_HOST Macro
533
UDP_OPEN_SERVER Macro
533
Stack Members
533
UDPInit Function
534
UDPProcess Function
534
UDPTask Function
535
Internal Members
535
activeUDPSocket Variable
536
FindMatchingSocket Function
536
LastPutSocket Variable
537
LOCAL_UDP_PORT_END_NUMBER Macro
537
LOCAL_UDP_PORT_START_NUMBER Macro
537
SocketWithRxData Variable
537
UDP_HEADER Structure
538
UDP_PORT Type
538
UDP_SOCKET_INFO Structure
538
UDPRxCount Variable
539
UDPSocketInfo Variable
539
UDPTxCount Variable
539
wGetOffset Variable
539
wPutOffset Variable
540 xxv
Microchip TCP/IP Stack Help Types UDP_STATE Enumeration
Wi-Fi API Wi-Fi Connection Profile Connection Profile Public Members
540 540
541 544 544
WF_CPCreate Function
545
WF_CPDelete Function
546
WF_CPGetAdHocBehavior Function
546
WF_CPGetBssid Function
547
WF_CPGetDefaultWepKeyIndex Function
547
WF_CPGetElements Function
548
WF_CPGetIds Function
548
WF_CPGetNetworkType Function
549
WF_CPGetSecurity Function
550
WF_CPGetSsid Function
551
WF_CPSetAdHocBehavior Function
551
WF_CPSetBssid Function
552
WF_CPSetDefaultWepKeyIndex Function
552
WF_CPSetElements Function
553
WF_CPSetNetworkType Function
553
WF_CPSetSecurity Function
554
WF_CPSetSsid Function
555
WFCPElementsStruct Structure
555
Connection Profile Internal Members
556
LowLevel_CPGetElement Function
557
LowLevel_CPSetElement Function
557
Wi-Fi Connection Algorithm Connection Algorithm Public Members
558 558
WF_CAGetBeaconTimeout Function
559
WF_CAGetBeaconTimeoutAction Function
560
WF_CAGetChannelList Function
561
WF_CAGetConnectionProfileList Function
561
WF_CAGetDeauthAction Function
562
WF_CAGetElements Function
562
WF_CAGetEventNotificationAction Function
563
WF_CAGetListenInterval Function
563
WF_CAGetListRetryCount Function
564
WF_CAGetMaxChannelTime Function
564
WF_CAGetMinChannelTime Function
565
WF_CAGetProbeDelay Function
565 xxvi
Microchip TCP/IP Stack Help WF_CAGetRssi Function
566
WF_CAGetScanCount Function
566
WF_CAGetScanType Function
567
WF_CASetBeaconTimeout Function
567
WF_CASetBeaconTimeoutAction Function
568
WF_CASetChannelList Function
569
WF_CASetConnectionProfileList Function
569
WF_CASetDeauthAction Function
570
WF_CASetElements Function
570
WF_CASetEventNotificationAction Function
571
WF_CASetListenInterval Function
571
WF_CASetListRetryCount Function
572
WF_CASetMaxChannelTime Function
573
WF_CASetMinChannelTime Function
573
WF_CASetProbeDelay Function
574
WF_CASetRssi Function
574
WF_CASetScanCount Function
575
WF_CASetScanType Function
575
WFCAElementsStruct Structure
576
Connection Algorithm Internal Members
577
LowLevel_CAGetElement Function
578
LowLevel_CASetElement Function
578
SetEventNotificationMask Function
579
Wi-Fi Connection Manager Connection Manager Public Members
580 580
WF_CMConnect Function
580
WF_CMDisconnect Function
581
WF_CMGetConnectionState Function
581
WF_CMInfoGetFSMStats Function
582
Wi-Fi Scan Scan Public Members
582 582
WF_Scan Function
583
WF_ScanGetResult Function
584
Wi-Fi Tx Power Control Tx Power Control Public Members
584 584
WF_TxPowerGetMinMax Function
585
WF_TxPowerSetMinMax Function
585
WF_TxPowerGetFactoryMax Function
586
Wi-Fi Power Save Power Save Public Members WF_GetPowerSaveState Function
586 587 587 xxvii
Microchip TCP/IP Stack Help WF_HibernateEnable Function
588
WF_PsPollDisable Function
589
WF_PsPollEnable Function
589
Power Save Internal Members
590
SendPowerModeMsg Function
590
SetPowerSaveState Function
590
Wi-Fi Miscellaneous Wi-Fi Miscellaneous Public Members
591 591
WF_GetDeviceInfo Function
592
WF_GetMacAddress Function
592
WF_GetMacStats Function
593
WF_GetMultiCastFilter Function
593
WF_GetRegionalDomain Function
594
WF_GetRtsThreshold Function
595
WF_SetMacAddress Function
595
WF_SetMultiCastFilter Function
596
WF_SetRegionalDomain Function
596
WF_SetRtsThreshold Function
597
tWFDeviceInfoStruct Structure
597
WFMacStatsStruct Structure
598
WF_ProcessEvent
599
Access Point Compatibility
601
WiFi Tips and Tricks
603
Hot Topics
604
Index
a
xxviii
1.2 Directory Structure
Microchip TCP/IP Stack Help
1 Introduction Welcome to the Microchip TCP/IP Stack! The Microchip TCP/IP Stack provides a foundation for embedded network applications by handling most of the interaction required between the physical network port and your application. It includes modules for several commonly used application layers, including HTTP for serving web pages, SMTP for sending e-mails, SNMP for providing status and control, Telnet, TFTP, Serial-to-Ethernet and much more. In addition, the stack includes light-weight and high-performance implementations of the TCP and UDP transport layers, as well as other supporting modules such as IP, ICMP, DHCP, ARP, and DNS. This help file serves two purposes. The first is to be a guide for first-time users of the TCP/IP Stack. The Getting Started section begins a series of pages to help you become familiar with the stack and configure it for use on a Microchip development board. The second purpose is to serve as a programmer's reference guide to the features and APIs available in the TCP/IP Stack. Updates The latest version of the Microchip TCP/IP Stack is always available at http://www.microchip.com/tcpip. New features are constantly being added, so check there periodically for updates and bug fixes.
Wi-Fi® is a registered trademark of the Wi-Fi Alliance.
1.1 Getting Help The TCP/IP Stack is supported through Microchip's standard support channels. If you encounter difficulties, you may submit ticket requests at http://support.microchip.com. The Microchip forums are also an excellent source of information, with a very lively community dedicated specifically to Ethernet and TCP/IP discussions at http://forum.microchip.com. Microchip also offers embedded network classes through Regional Training Centers. For more information, visit http://www.microchip.com/rtc.
1.2 Directory Structure The TCP/IP Stack comes with many files, tools, documents, and project examples. Before getting started, take a moment to familiarize yourself with the directory structure so that you may find what you need quickly. Installing the stack will produce the following structure:
1
1.2 Directory Structure
Microchip TCP/IP Stack Help
Several demonstration projects are installed into the TCPIP directory in the default Microchip Solutions v20xx-xx-xx directory. In your projects, you may wish to write your application code in a project folder located in the same place as the demo project folders. For more information about specific demos, see the list of demo projects ( see page 83) in this help file. These project folders may contain additional subdirectories: • A Configs subdirectory will contain alternative copies of the TCPIPConfig.h and HardwareProfile.h configuration files, pre-configured to work with different demo boards. The default copies of these files in the demo folder will include one of these alternative files based on a macro defined in the demo project. • An SSLKeys subdirectory will contain sample security keys and certificates. • A WebPages2 subdirectory will contain sample web pages for use with the MPFS2 file system. • An MPLAB.X project folder contains the MPLAB X project files for the demo. • A Precompiled Hex subdirectory contains precompiled hex images of the demo project. Other stack-specific folders include are: • The Microchip folder contains stack files and components. • The Include sub-folder under the Microchip folder contains header files for Microchip stack and library solutions. The TCPIP Stack folder in the Include folder contains headers for the TCP/IP Stack. • The TCPIP Stack folder in the Microchip folder contains C source files, documentation, and stack utilities. • The Demo Board Files subdirectory contains information about the different demo boards ( run the TCP/IP stack.
see page 64) that can
• The Utilities subdirectory contains PC-based utilities that can help when using the stack. See the Software ( see page 59) section for more information. The source code for the Microchip TCP/IP Discoverer ( see page 62), the MPFS2 ( see page 59) tool, and the MPFS library is located in the Source subdirectory in the Utilities directory. In most cases, it will not be necessary to modify source or header files in the Microchip directory.
2
2
Microchip TCP/IP Stack Help
2 SW License Agreement MICROCHIP IS WILLING TO LICENSE THE ACCOMPANYING SOFTWARE AND DOCUMENTATION TO YOU ONLY ON THE CONDITION THAT YOU ACCEPT ALL OF THE FOLLOWING TERMS. TO ACCEPT THE TERMS OF THIS LICENSE, CLICK "I ACCEPT" AND PROCEED WITH THE DOWNLOAD OR INSTALL. IF YOU DO NOT ACCEPT THESE LICENSE TERMS, CLICK "I DO NOT ACCEPT," AND DO NOT DOWNLOAD OR INSTALL THIS SOFTWARE.
NON-EXCLUSIVE SOFTWARE LICENSE AGREEMENT
This Nonexclusive Software License Agreement ("Agreement") is a contract between you, your heirs, successors and assigns ("Licensee") and Microchip Technology Incorporated, a Delaware corporation, with a principal place of business at 2355 W. Chandler Blvd., Chandler, AZ 85224-6199, and its subsidiary, Microchip Technology (Barbados) II Incorporated (collectively, "Microchip") for the accompanying Microchip software including, but not limited to, Graphics Library Software, IrDA Stack Software, MCHPFSUSB Stack Software, Memory Disk Drive File System Software, mTouch(TM) Capacitive Library Software, Smart Card Library Software, TCP/IP Stack Software, MiWi(TM) DE Software, and/or any PC programs and any updates thereto (collectively, the "Software"), and accompanying documentation, including images and any other graphic resources provided by Microchip ("Documentation").
1. Definitions. As used in this Agreement, the following capitalized terms will have the meanings defined below: a. "Microchip Products" means Microchip microcontrollers and Microchip digital signal controllers. b. "Licensee Products" means Licensee products that use or incorporate Microchip Products. c. "Object Code" means the Software computer programming code that is in binary form (including related documentation, if any), and error corrections, improvements, modifications, and updates. d. "Source Code" means the Software computer programming code that may be printed out or displayed in human readable form (including related programmer comments and documentation, if any), and error corrections, improvements, modifications, and updates. e. "Third Party" means Licensee’s agents, representatives, consultants, clients, customers, or contract manufacturers. f. "Third Party Products" means Third Party products that use or incorporate Microchip Products.
2. Software License Grant. Microchip grants strictly to Licensee a non-exclusive, non-transferable, worldwide license to: a. use the Software in connection with Licensee Products and/or Third Party Products; b. if Source Code is provided, modify the Software, provided that no Open Source Components (defined in Section 5 below) are incorporated into such Software in such a way that would affect Microchip’s right to distribute the Software with the limitations set forth herein and provided that Licensee clearly notifies Third Parties regarding such modifications; c. distribute the Software to Third Parties for use in Third Party Products, so long as such Third Party agrees to be bound by this Agreement (in writing or by "click to accept ( see page 166)") and this Agreement accompanies such distribution; d. sublicense to a Third Party to use the Software, so long as such Third Party agrees to be bound by this Agreement (in writing or by "click to accept ( see page 166)"); e. with respect to the TCP/IP Stack Software, Licensee may port the ENC28J60.c, ENC28J60.h, ENCX24J600.c, and ENCX24J600.h driver source files to a non-Microchip Product used in conjunction with a Microchip ethernet controller; f. with respect to the MiWi (TM) DE Software, Licensee may only exercise its rights when the Software is embedded on a Microchip Product and used with a Microchip radio frequency transceiver or UBEC UZ2400 radio frequency transceiver 3
2
Microchip TCP/IP Stack Help which are integrated into Licensee Products or Third Party Products. For purposes of clarity, Licensee may NOT embed the Software on a non-Microchip Product, except as described in this Section.
3. Documentation License Grant. Microchip grants strictly to Licensee a non-exclusive, non-transferable, worldwide license to use the Documentation in support of Licensee's authorized use of the Software
4. Third Party Requirements. Licensee acknowledges that it is Licensee’s responsibility to comply with any third party license terms or requirements applicable to the use of such third party software, specifications, systems, or tools. Microchip is not responsible and will not be held responsible in any manner for Licensee’s failure to comply with such applicable terms or requirements.
5. Open Source Components. Notwithstanding the license grant in Section 1 above, Licensee further acknowledges that certain components of the Software may be covered by so-called "open source" software licenses ("Open Source Components"). Open Source Components means any software licenses approved as open source licenses by the Open Source Initiative or any substantially similar licenses, including without limitation any license that, as a condition of distribution of the software licensed under such license, requires that the distributor make the software available in source code format. To the extent required by the licenses covering Open Source Components, the terms of such license will apply in lieu of the terms of this Agreement. To the extent the terms of the licenses applicable to Open Source Components prohibit any of the restrictions in this Agreement with respect to such Open Source Components, such restrictions will not apply to such Open Source Component.
6. Licensee Obligations. Licensee will not: (i) engage in unauthorized use, modification, disclosure or distribution of Software or Documentation, or its derivatives; (ii) use all or any portion of the Software, Documentation, or its derivatives except in conjunction with Microchip Products or Third Party Products; or (iii) reverse engineer (by disassembly, decompilation or otherwise) Software or any portion thereof. Licensee may not remove or alter any Microchip copyright or other proprietary rights notice posted in any portion of the Software or Documentation. Licensee will defend, indemnify and hold Microchip and its subsidiaries harmless from and against any and all claims, costs, damages, expenses (including reasonable attorney's fees), liabilities, and losses, including without limitation product liability claims, directly or indirectly arising from or related to the use, modification, disclosure or distribution of the Software, Documentation, or any intellectual property rights related thereto; (ii) the use, sale and distribution of Licensee Products or Third Party Products; and (iii) breach of this Agreement.
7. Confidentiality. Licensee agrees that the Software (including but not limited to the Source Code, Object Code and library files) and its derivatives, Documentation and underlying inventions, algorithms, know-how and ideas relating to the Software and the Documentation are proprietary information belonging to Microchip and its licensors ("Proprietary Information"). Except as expressly and unambiguously allowed herein, Licensee will hold in confidence and not use or disclose any Proprietary Information and will similarly bind its employees and Third Party(ies) in writing. Proprietary Information will not include information that: (i) is in or enters the public domain without breach of this Agreement and through no fault of the receiving party; (ii) the receiving party was legally in possession of prior to receiving it; (iii) the receiving party can demonstrate was developed by the receiving party independently and without use of or reference to the disclosing party's Proprietary Information; or (iv) the receiving party receives from a third party without restriction on disclosure. If Licensee is required to disclose Proprietary Information by law, court order, or government agency, License will give Microchip prompt notice of such requirement in order to allow Microchip to object or limit such disclosure. Licensee agrees that the provisions of this Agreement regarding unauthorized use and nondisclosure of the Software, Documentation and related Proprietary Rights are necessary to protect the legitimate business interests of Microchip and its licensors and that monetary damage alone cannot adequately compensate Microchip or its licensors if such provisions are violated. Licensee, therefore, agrees that if Microchip alleges that Licensee or Third Party has breached or violated such provision then Microchip will have the right to injunctive relief, without the requirement for the posting of a bond, in addition to all other remedies at law or in equity.
4
2
Microchip TCP/IP Stack Help 8. Ownership of Proprietary Rights. Microchip and its licensors retain all right, title and interest in and to the Software and Documentation including, but not limited to all patent, copyright, trade secret and other intellectual property rights in the Software, Documentation, and underlying technology and all copies and derivative works thereof (by whomever produced). Licensee and Third Party use of such modifications and derivatives is limited to the license rights described in Sections this Agreement.
9. Termination of Agreement. Without prejudice to any other rights, this Agreement terminates immediately, without notice by Microchip, upon a failure by Licensee or Third Party to comply with any provision of this Agreement. Upon termination, Licensee and Third Party will immediately stop using the Software, Documentation, and derivatives thereof, and immediately destroy all such copies.
10. Warranty Disclaimers. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. MICROCHIP AND ITS LICENSORS ASSUME NO RESPONSIBILITY FOR THE ACCURACY, RELIABILITY OR APPLICATION OF THE SOFTWARE OR DOCUMENTATION. MICROCHIP AND ITS LICENSORS DO NOT WARRANT THAT THE SOFTWARE WILL MEET REQUIREMENTS OF LICENSEE OR THIRD PARTY, BE UNINTERRUPTED OR ERROR-FREE. MICROCHIP AND ITS LICENSORS HAVE NO OBLIGATION TO CORRECT ANY DEFECTS IN THE SOFTWARE.
11. Limited Liability. IN NO EVENT WILL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER ANY LEGAL OR EQUITABLE THEORY FOR ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS. The aggregate and cumulative liability of Microchip and its licensors for damages hereunder will in no event exceed $1000 or the amount Licensee paid Microchip for the Software and Documentation, whichever is greater. Licensee acknowledges that the foregoing limitations are reasonable and an essential part of this Agreement.
12. General. THIS AGREEMENT WILL BE GOVERNED BY AND CONSTRUED UNDER THE LAWS OF THE STATE OF ARIZONA AND THE UNITED STATES WITHOUT REGARD TO CONFLICTS OF LAWS PROVISIONS. Licensee agrees that any disputes arising out of or related to this Agreement, Software or Documentation will be brought in the courts of the State of Arizona. This Agreement will constitute the entire agreement between the parties with respect to the subject matter hereof. It will not be modified except by a written agreement signed by an authorized representative of the Microchip. If any provision of this Agreement will be held by a court of competent jurisdiction to be illegal, invalid or unenforceable, that provision will be limited or eliminated to the minimum extent necessary so that this Agreement will otherwise remain in full force and effect and enforceable. No waiver of any breach of any provision of this Agreement will constitute a waiver of any prior, concurrent or subsequent breach of the same or any other provisions hereof, and no waiver will be effective unless made in writing and signed by an authorized representative of the waiving party. Licensee agrees to comply with all export laws and restrictions and regulations of the Department of Commerce or other United States or foreign agency or authority. The indemnities, obligations of confidentiality, and limitations on liability described herein, and any right of action for breach of this Agreement prior to termination, will survive any termination of this Agreement. Any prohibited assignment will be null and void. Use, duplication or disclosure by the United States Government is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer-Restricted Rights clause of FAR 52.227-19 when applicable, or in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, and in similar clauses in the NASA FAR Supplement. Contractor/manufacturer is Microchip Technology Inc., 2355 W. Chandler Blvd., Chandler, AZ 85224-6199.
If Licensee has any questions about this Agreement, please write to Microchip Technology Inc., 2355 W. Chandler Blvd., Chandler, AZ 85224-6199 USA. ATTN: Marketing.
5
2
Microchip TCP/IP Stack Help
Copyright (c) 2011 Microchip Technology Inc. All rights reserved.
License Rev. No. 04-091511
6
3
Microchip TCP/IP Stack Help
3 Release Notes ****** Microchip TCP/IP Stack Version Log: ****** Remarks Please file bug-reports/bug-fixes at http://support.microchip.com/ or post to the Microchip TCP/IP -> Ethernet Forum at http://forum.microchip.com/ Look for stack updates at http://www.microchip.com/mal/
****** v5.36.4 Oct 2011 ****** Changes: 1. SNMPNotify ( see page 323)() is updated to support ASCII string varible type for both TRAPv1 and TRAPv2.ASCII string address pointer is assigned to argument val(SNMP_VAL ( see page 320)) of SNMPNotify ( see page 323)(). 2. The SSL module has been updated to support 1024-bit RSA key lengths for server and client on all architectures. PIC32 microcontrollers now support client/server RSA key lengths of 2048 bits. NOTE: To support these changes, you must manually modify your copy of RSA.c. A description of the required changes ("Required SSL Changes.pdf") can be found in your Microchip Applications Libraries installation directory in the "MicrochipHelpSupplementary TCPIP Help" subdirectory. Fixes: 1. SNMP local variable community length increased with plus one.SNMP warnings has been removed for the compiler version C32 2.01 for zero optimisation. 2. Updated MPFS2.jar and mib2bib.jar to support Java version 1.7. 3. Fixed MPFS2.jar offset issue for fileRcrd.bin and dynRcrd.bin file and it was due to the file which has zero dynamic variable.Fixed Crimson editor problem with webPage2 folder where user couldn't save files using Crimson Editor if the WebPages2 folder that contained those files was selected in the MPFS2 utility. 4. MPFS2.jar file was getting hanged for the zero file size access.Now Zero file size also is the part of the respective generated files. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. LCDBlocking.c timing for the LCD_E_IO enable signal is too fast to meet published data sheet limits for various LCD controllers when compiling for a PIC32 running at > 43MHz. Despite this potential timing violation, the LCD does normally work correctly on the precompiled PIC32 demos for the Explorer 16 at 80MHz. 4. For PIC32 implementations, depending on the configuration, it is possible that the MACGetFreeRxSize() returns a value greater than 64 KB. For backward compatibility reasons the stack uses a 16 bit value to check the returned value and it won't work corretly. 5. Limiting the number of UDP sockets to 8 in the stack demos may prevent SNMP trap functionality. If this occurs, you can increase the MAX_UDP_SOCKETS definition in TCPIPConfig.h to 10 (if your system will support the increased data memory usage) to fix this issue. 7
3
Microchip TCP/IP Stack Help 6. The SNMP mib file's date and version parameter does not match the date/version of the current stack release.
****** v5.36.2 July 2011 ****** Changes: 1. Removed the Google PowerMeter and Google PowerMeter EZConfig demos. Google, Inc. has deprecated Google PowerMeter and has expressed the intent to remove access to it on September 16, 2011. To obtain Microchip Technology's Google PowerMeter reference implementation, you can download the June 2011 Microchip Application Libraries archived release from www.microchip.com/mal. 2. Modified the Energy Monitoring demo to remove Google PowerMeter functionality. The demo will still display measured power data on its internal web page. 3. Updated the TCP/IP Stack Performance table to use the testing methodology from previous releases. More information is available in the TCP/IP Stack Help file. 4. gSnmpNonMibRecInfo ( see page 114)[] has been moved from snmp.c file to CustomSNMPApp.c file and SNMP_MAX_NON_REC_ID_OID ( see page 115) macro has been moved from snmp.h file to CustomSNMPApp.c file. gSnmpNonMibRecInfo ( see page 114)[] is used to list the static variables parent OID strings which are not part of mib.h file. This structure is used to restrict the access to the SNMPv3 objects from SNMPv2c and SNMPv1 version requests. Macro STACK_USE_SMIV2 ( see page 115) is used to support gSnmpNonMibRecInfo ( see page 114)[] with MODULE-IDENTITY number. For V5.31 STACK_USE_SMIV2 ( see page 115) need to commented. 5. Removed the SPI2CON register freeze-on-halt bit macro from the SPIFlash, RAM, and EEPROM driver files to provide compatibility with C32 v2.00. Fixes: 1. Removed the MPFSImg2 files from the MPLAB X C18/C30 projects so that the projects will compile. Disabled MPFSImg2.c for PIC32 Explorer 16 projects. 2. Added a heap and minimum stack size for the PIC32 Ethernet Starter Kit MPLAB X project. 3. The TCP/IP Stack Help File's performance table has been updated using the same test procedure used in previous releases. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. LCDBlocking.c timing for the LCD_E_IO enable signal is too fast to meet published data sheet limits for various LCD controllers when compiling for a PIC32 running at > 43MHz. Despite this potential timing violation, the LCD does normally work correctly on the precompiled PIC32 demos for the Explorer 16 at 80MHz. 4. For PIC32 implementations, depending on the configuration, it is possible that the MACGetFreeRxSize() returns a value greater than 64 KB. For backward compatibility reasons the stack uses a 16 bit value to check the returned value and it won't work corretly. 5. Limiting the number of UDP sockets to 8 in the stack demos may prevent SNMP trap functionality. If this occurs, you can increase the MAX_UDP_SOCKETS definition in TCPIPConfig.h to 10 (if your system will support the increased data memory usage) to fix this issue. 6. The SNMP mib file's date and version parameter does not match the date/version of the current stack release.
****** v5.36 2 June 2011 8
3
Microchip TCP/IP Stack Help
****** Changes: 1. Because of changes to the SHOUTcast server configuration, the Internet Radio demo is no longer functional. This demo has been retained in the stack distribution to provide a TCP/IP code example. 2. The UDP module will now perform address resolution and DNS querying automatically. As a result, the UDP module APIs have changed. The UDPOpenEx ( see page 523) function provides this additional functionality. Please consult the TCP/IP Stack Help File's "Stack API > UDP" topic for more information. 3. The UDPOpen (
see page 524) macro has been added to conform to the legacy UDPOpen (
see page 524) interface.
4. The Announce ( see page 152), BerkeleyAPI, DHCP client/server, DNS client/server, NBNS, Reboot ( see page 314), SNMP, SNTP, TFTPc, UDPPerformanceTest, and ZeroConf modules have been updated to use the new UDP API. The iPerf demo has also been updated. 5. The MPFS Classic and HTTP(1) modules have been removed from the stack. Function- ality to support these modules has also been removed from the TCP/IP Stack software tools. MPFS2 and HTTP2 are still supported. 6. The UARTConfig demo module has been updated to upload MPFS2 images to the demo board in place of MPFS Classic images. 7. To facilitate linking on PIC18 platforms, the number of UDP sockets in demo projects has been reduced from 10 to 8. 8. The SNMP Stack application and mib2bib.jar PC utility now both support 1024 dynamic IDs. 9. SNMP_DEMO_TRAP is a new dynamic variable added to the snmp.mib file to support SMIv2 with TRAPv2. This will correct a previously existing issue viewing traps with the iReasoning MIB browser. As per those changes, the mchp.mib file has been modified to support the SMIv2 standard. This mib includes MODULE-IDENTITY which will provide MICROCHIP and MIB information. snmp.mib also includes MODULE-IDENTIY(1), a new number (1) to the existing OID after ENTERPRISE-ID(17095). 10. Added a preprocessor check that will include the ultoa function if a version of the C32 compiler earlier than 1.12 is used. 11. Modified the WiFi module to use separate retry counters for AdHoc and Infrastructure modes. 12. Modified Berkeley API module to accept ( see page 166) IPPROTO_IP ( see page 171) as a valid protocol for the socket function. The code will determine the protocol type from the socket type (datagram or stream). 13. Created MPLAB X projects corresponding to most MPLAB 8 projects and configurations. These projects are located in the MPLAB.X subfolder in the associated demo project directory. The MPLAB X import wizard can be used to create MPLAB X projects from MPLAB 8 projects that don't have an analogue in the new demo project folders. 14. Added project support for the dsPIC33E and PIC24E architectures. 15. All TCP/IP Stack demo projects have been moved to the "TCPIP" subdirectory in the stack installation directory. 16. Created Java versions of several TCP/IP tools to provide cross-platform support. The TCP/IP Configuration Wizard has not been ported to Java; thus, it is only available for Windows users. 17. To prevent issues with path length, MPLAB 8 project names have been changed. A list of the abbreviations used in the project names is available in the MAL help folder (Microchip Solutions/Microchip/Help/Abbreviations.htm). The names of the HardwareProfile and TCPIPConfig configuration files have been abbreviated as well. 18. Changed the configuration inclusion macros used by the TCP/IP Stack demo projects to match the terms used in the project/configuration names. 19. The "Alternative Configurations" subfolders in most demo projects has been renamed to "Configs." 20. Added a Google PowerMeter demo for use with the PIC18F87J72 Energy Monitoring PICtail. 21. The Web Preview tool is no longer included with the stack. Fixes: 1. Fixed a DHCP Server (DHCPs.c) lease leak problem that would occur when STACK_USE_ZEROCONF_LINK_LOCAL was defined. This problem would have resulted in the DHCP server stop giving out any leases until being rebooted. 2. Updated the PIC32MX6XX/7XX external PHY SMSC 8720LAN reference design. 3. Fixed bug with window expecting MACGetFreeRxSize() to return values < 32KB. 4. Fixed a type casting bug with the CalcIPChecksum ( see page 213) function that would cause an incorrect TX checksum if the checksum value overflowed again after adding the carry bits to the checksum value.
9
3
Microchip TCP/IP Stack Help 5. Fixed a bug in the AutoIP module that may have prevented the module from correctly defending its own address. 6. Added a check to the Announce ( see page 152) module to ensure the MAC layer is linked before attemping to transmit an Announce ( see page 152) message. 7. Fixed a bug in the ETH97J60 MACPut function. 8. Added an additional preprocessor check in a debug menu setting in WF_Spi.c to prevent a build error. 9. Added a fix to the Google PowerMeter demo code to restore SNTP timestamp sourcing if SNTP is enabled. Previously, it would be overwritten by a possibly invalid HTTP timestamp. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. LCDBlocking.c timing for the LCD_E_IO enable signal is too fast to meet published data sheet limits for various LCD controllers when compiling for a PIC32 running at > 43MHz. Despite this potential timing violation, the LCD does normally work correctly on the precompiled PIC32 demos for the Explorer 16 at 80MHz. 4. For PIC32 implementations, depending on the configuration, it is possible that the MACGetFreeRxSize() returns a value greater than 64 KB. For backward compatibility reasons the stack uses a 16 bit value to check the returned value and it won't work corretly. 5. Limiting the number of UDP sockets to 8 in the stack demos may prevent SNMP trap functionality. If this occurs, you can increase the MAX_UDP_SOCKETS definition in TCPIPConfig.h to 10 (if your system will support the increased data memory usage) to fix this issue. 6. The SNMP mib file's date and version parameter does not match the date/version of the current stack release.
****** v5.31 19 October 2010 ****** Changes: 1. Reorganized demo projects. The TCPIP ENCX24J600 Demo App, TCPIP PIC32 ETH Demo App, and TCPIP WiFi Demo App projects in stack versions 5.25 and prior have all been merged into the TCPIP Demo App folder. All four of these projects were almost identical to each other, with the primary difference being the network interface controller the projects were preconfigured to support. In this 5.31 TCP/IP Stack release, each hardware combination now has its own MPLAB IDE project in the TCPIP Demo App folder. 2. Reorganized HardwareProfile.h and TCPIPConfig.h structure for the TCPIP Demo App, TCPIP Google PowerMeter Demo App, and TCPIP WebVend App projects. Now, instead of having one massive HardwareProfile.h file that supports a multitude of hardware platforms simultaneously, simple individual hardware profiles have been created for specific hardware combinations and placed in the "Alternative Configurations" sub-folder. The correct hardware profile or TCPIP config file is selected by #including "HardwareProfile.h" or "TCPIPConfig.h" as in previous stack versions. However, the active hardware profile or config file from the Alternative Configurations folder is selected by a preprocessor macro defined in the MPLAB project settings (passed on the command line to the compiler). 3. Added HTTP_SAVE_CONTEXT_IN_PIC_RAM option to TCPIPConfig.h (HTTP2 server module). This option, when enabled, will increase HTTP2 server performance when servicing multiple simultaneous connections at the expense of using more PIC RAM. 4. Added automatic TPIN+/- polarity swapping logic to ETH97J60.c driver for PIC18F97J60 family devices. Some 3rd party Ethernet switches, routers, and end devices have their TX+/- pins wired backwards such that the remote TX+ signal connects to the PIC TPIN- pin and the remote TX- signal connects to the PIC TPIN+ pin. Because 10BaseT Ethernet signaling is polarized and the PIC18F97J60 family does not implement an auto-polarity feature, this normally prevents all RX communications with these non-IEEE 802.3 compliant link partners. To work around this incompatibility, it is possible to implement circuitry to swap the RX+ and RX- signals before reaching the TPIN+ and TPIN- pins. The PICDEM.net 2 Rev 6 reference design includes this necessary circuitry (U6, U7, R54, and RX_SWAP GPIO output pin from PIC). This 10
3
Microchip TCP/IP Stack Help stack version automatically controls the RX_SWAP signal based on the ETH_RX_POLARITY_SWAP_TRIS and ETH_RX_POLARITY_SWAP_IO definitions in HardwareProfile.h. If these macros are undefined, then the automatic polarity swapping feature is disabled in the ETH97J60.c driver. 5. Added portable LFSRRand ( see page 225)() and LFSRSeedRand ( see page 226)() public functions to Helpers.c and removed all references to C rand() and srand() functions. The C rand() function returns a 15 bit integer on 8 and 16 bit PICs, but a 31 bit integer on PIC32s. The LFSRRand ( see page 225)() function returns a 16-bit integer, regardless of which PIC you are using. 6. Added support for various SST/Microchip brand SST25xxxxx SPI Flash chips to SPIFlash.c driver. Previously only devices supporting the Auto Address ( see page 144) Increment (AAI) Word Program opcode (0xAD) would work. Now, devices such as the SST2525VF010A should work, which require the AAI Byte program opcode (0xAF) instead. 7. Removed support for Spansion brand SPI Flash chips in the SPIFlash.c driver. If your application is already using one of these devices, continue to use the SPIFlash.c/.h files from TCP/IP Stack 5.25. These older files are API compatible with the current version, so can be dropped in by simply overwriting the SPIFlash.c and SPIFlash.h files. 8. Removed a -4 offset from the advirtised TCP Maximum Segment Size option (MSS) and TCP_MAX_SEG_SIZE_RX ( see page 480) configuration value in TCP.c. The default TCP MSS advertised is now 536 instead of 532. 9. For Wi-Fi projects in the TCPIP Demo App folder, changed MY_DEFAULT_LIST_RETRY_COUNT to WF_RETRY_FOREVER instead of 3. This changes default connection behavior to keep trying to connect ( 168) instead of just trying 3 times which makes more sense for demonstration.
see page
10. Changed WF_Connect() beacon timeout to 40. 11. IFConfig command in TCPIP WiFi Console Demo App modified to return application-perspective MAC address from the AppConfig structure, and not the Wi-Fi serialized MAC address (they may not match if user desired custom MAC). 12. Updated the TCP/IP Configuration Wizard. The user can now configure wireless settings and stack settings seperately. Because of the changes to the TCPIPConfig.h file, the user must now select the specific copy of TCPIPConfig.h (or any of its variants) instead of selecting a project directory. Added the ability to select WF_RETRY_FOREVER in the Wi-Fi configuration settings. Added a selection parameter for BSD socket count. Added validation to check for the proper number of Berkeley sockets and TCP performance test sockets in the socket configuration screen (Advanced Settings) if either of these features are enabled. Added the ability to create sockets of the same type with different TX/RX buffer sizes in the socket configuration screen. 13. Updated the TCPIP WebVend Demo App to support Wi-Fi in several configurations. 14. Modified the Google PowerMeter demo to automatically determine the date/time from the HTTP module if the date/time cannot be obtained from the SNTP module. 15. Added a new Google Map project example to the Combo Demos folder. This example runs on a PIC24FJ256DA210 Development Board + Fast 100Mbps Ethernet PICtail Plus (or Ethernet PICtail Plus) + Truly 3.2" 240x320 display, TFT_G240320LTSW_118W_E (or Powertip 4.3" 480x272 display, PH480272T_005_I11Q). It also can run on the PIC32 Multimedia Expansion Board + PIC32 Ethernet Starter Kit. This demo connects to the Internet, sends an HTTP query for a specific map tile to the Google Static Maps API, and then displays the compressed tile to the graphics display. For more information, see the "Getting Started - Running the Graphics Google Map Demo.htm" file in the Combo DemosGoogle Map folder. 16. Added preliminary SNMPv3 module. This module, enabled with the STACK_USE_SNMPV3_SERVER option in TCPIPConfig.h, implements the Simple Network Management Protocol, version 3. Among other things, SNMPv3 adds secure authentication and cryptographic privacy as compared to SNMPv2C. This implementation currently only supports AES encryption (no DES support). It also has only been tested with the PIC32 Ethernet Starter Kit (TCPIP Demo App C32 - PIC32_ENET_SK_DM320004_INTERNAL_ETHERNET.mcp MPLAB IDE project). SNMPv3 on PIC18, PIC24, and dsPIC platforms are not supported at this time. Because AES encryption has specialized United States export requirements, this TCP/IP Stack release does not include the required AES library to enable SNMPv3. To obtain the needed AES library, you must purchase SW300052 v2.6 or later. Older v2.5 and previous versions include AES related files on them, but do not include the new AES files required by SNMPv3. For more information on using SNMP, refer to the TCP/IP Stack Help (Demo Information -> Available Demos -> TCPIP Demo App -> Demo Modules -> Network Management (SNMP) Server). 17. Altered the SaveAppConfig() function in MainDemo.c to store a more robust signature to EEPROM/SPI Flash when saving the AppConfig structure. In v5.25 and prior stack versions, when EEPROM or SPI Flash memory was available, the stack would automatically write a one byte marker character to address 0x000000 in the EEPROM/Flash indicating if a valid AppConfig structure was stored in the non-volatile memory. This resulted in the EEPROM/Flash contents being organized like the following: Address ( see page 144) Data Contents =================== ============================================== 0x000000: Marker Byte 0x000001: AppConfig structure MPFS_RESERVE_BLOCK: Start of MPFS/MPFS2 image containing web pages In this stack version, EEPOM/Flash contents will now contain: Address ( see page 144) Data Contents =================== ============================================== 0x000000: Length of AppConfig structure (16-bit integer) 11
3
Microchip TCP/IP Stack Help 0x000002: IP checksum of the AppConfig default values, as defined in TCPIPConfig.h and WF_Config.h (16-bit integer). 0x000004: IP checksum of the subsequent EEPROM/Flash bytes of the AppConfig values. 0x000006: AppConfig structure MPFS_RESERVE_BLOCK: Start of MPFS/MPFS2 image containing web pages The additional checkums allow automatic detection to occur if you change one of the values in TCPIPConfig.h or WF_Config.h that affects AppConfig. If you change one of the values in code, then upon boot up, the application will automatically detect this change and start using the values that you selected in code. If, at run time, you decide to change the AppConfig values and commit the changes to EEPROM/Flash, then the stack will subsequently use the run-time saved values on future reboots. The checksum at offset 0x000004 ensures that if any corrupted AppConfig contents are found in EEPROM/Flash (ex: power is lost between writing the signature structure and actual AppConfig structure, or code unintentionally overwrites something in the AppConfig memory area), then the original defaults defined in TCPIPConfig.h and WF_Config.h will be used instead of the corrupted values. This EEPROM/SPI Flash change affects all projects except TCPIP Internet Radio App, TCPIP Internet Bootloader App, and all PIC32 Starter Kit projects since these projects do not have or use external EEPROM or SPI Flash memory. Fixes: 1. Fixed a UDP bug in which a transmitted packet would have been addressed to the wrong destination node if the UDP socket received a broadcast packet from a different remote node from the last received packet, but using the same source port number as the last received packet. The FindMatchingSocket ( see page 473)() function in UDP.c will now always change the local socket parameters to send to the most recent remote node's unicast IP address, regardless of if the last received packet was addressed to a multicast or broadcast destination. Thanks go to Billy Walton for reporting this erroneous behavior. If you wish to change the destination IP/MAC addresses or port number for a UDP packet that you are ready to send, write the new parameters to the UDPSocketInfo ( see page 539)[SocketHandle] global structure before calling UDPFlush ( see page 526)(). This structure contains remoteNode and remotePort parameters for the remote IP address/MAC address and remote UDP port, respectively. You can also read these values to obtain the remote addressing parameters for the last received packet on the given UDP socket. Note that "SocketHandle" refers to the UDP socket handle returned by the UDPOpen ( see page 524)() API, not the literal string "SocketHandle". 2. Fixed ADC state save/restore bug in GenerateRandomDWORD ( see page 217)() function in Helpers.c. PIC24, dsPIC, and PIC32 platforms require the ADC ON/ADON bit to be cleared before modifying certain other ADC register contents. 3. Fixed an ENC28J60 MAC/MII register write timing violation when using a PIC24H or dsPIC at over 33MIPS. There was inadequate Chip Select hold time provided, violating the 210ns minimum specified in the ENC28J60 data sheet. This violation may have resulted in certain devices losing the ability to receive packets (due to the MARXEN bit, MACON1, getting cleared unintentionally). 4. Fixed an ENCX24J600.c driver bug in which operating at 100Mbps with the ENC424J600/624J600 Ethernet controller, it would be possible for the MACGetHeader() function to issue a Reset() operation under rare circumstances. The PIC would reset whenever the PHY detected an illegal symbol during 4B5B decoding but guessed the correct 4B symbol such that no data corruption or CRC error occurred. This condition results in a valid packet being received but with the Received Ok Receive Status Vector bit being clear (RSV == 0). This issue would become more probable when using very long Ethernet cables (ex: 100 meters) and receiving a lot of data. 5. Fixed a TCP bug in which calling TCPDisconnect ( see page 446)() to close a connection when the remote node's RX window was 0 bytes would have caused the stack to enter an infinite loop sending duplicate ACK packets. 6. Fixed Wi-Fi bug that caused assert condition if too many management messages were being received during data traffic. 7. Fixed Wi-Fi bug that caused WF_EVENT_CONNECTION_RESTABLISHED event case to send the wrong notification to the app. 8. Fixed Wi-Fi bug that caused assert failure with Scratch move failure. 9. Fixed Wi-Fi bug in WF_CAGetChannelList (
see page 561)() and WF_CAGetSecurity that caused failure.
10. Fixed Wi-Fi EasyConfig bug that required development boards to be manually reset even after new network was selected. 11. Fixed MRF24WB0 bug that caused assert if invalid WPA/WPA2 key was entered. 12. Fixed Wi-Fi power management bit behavior in PS-Poll frame that was causing some AP’s to never send data or disconnect when in power save mode. 13. Fixed a TCP bug in which attempting to open a client TCP socket to a remote server, specified by IP address (not DNS address), that was offline, but who's MAC address was already cached by the ARP client, would result in endless back-offs. For example, when attempting to contact the remote node (that was not responding), the TCP module would have transmitted a SYN at time T=0 seconds, T=1s, T=3s, T=7s, T=15s, T=31s, T=63s, T=127s, T=255s, etc. The exponential back-off between retransmissions would grow indefinitely until the retransmission interval would have grown so large that effectively no-retransmissions would be occurring. Assuming the application wasn't written with its own 12
3
Microchip TCP/IP Stack Help timeout to prevent endless waiting, this would prevent the socket from automatically establishing the connection to the remote server once the server came back online. With this TCP fix, the exponential back off now saturates after TCP_MAX_RETRIES ( see page 480) (5) back offs and continues to retransmit using the same interval. By default, this means SYN transmissions will occur at T=0 seconds, T=1s, T=3s, T=7s, T=15s, T=31s, T=63s, T=95s, T=127s, etc. After 5 back-offs the retransmission interval stops growing and stays constant at 32 seconds. 14. Fixed an RSA computation bug that would cause the RSA module to never complete if you attempted to compute y = x^e % n where e = 3 (or similar number < 256 with only 0, 1, or 2 bits set). Thanks go to Kevin Maidment for pointing this error out and suggesting a solution. Note, that this fix to RSA.c is not distributed with the ordinary TCP/IP Stack due to United States export restrictions. To get this fix, you must repurchase SW300052. This fix is included in SW300052 v2.6 or later. If you don't have CD media to identify the SW300052 version that you have, you can test the RSA.c file that you have. RSA.c in SW300052 v2.6 has a CRC32 checksum of 0x91F66711. RSA.c in v2.5 and prior had a checksum of 0xB1E8B0CC. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. LCDBlocking.c timing for the LCD_E_IO enable signal is too fast to meet published data sheet limits for various LCD controllers when compiling for a PIC32 running at > 43MHz. Despite this potential timing violation, the LCD does normally work correctly on the precompiled PIC32 demos for the Explorer 16 at 80MHz.
****** v5.25 07 May 2010 ****** Changes: 1. Added support for the Microchip MRF24WB0 802.11 WiFi controller (module part number MRF24WB0MA). This product is intended as a backwards compatible, drop in replacement to the ZG2100. The MRF24WB0MA should work with previous TCP/IP Stack versions as if it were a ZG2100M, but when the MRF24WB0MA is used with this (5.25) and future TCP/IP Stack versions, feature improvements inside the MRF24WB0 allow the TCP/IP Stack code/RAM size to be smaller and run faster. 2. Dropped support for the ZeroG ZG2100 802.11 WiFi controller. Applications that must stay with this device should continue to use TCP/IP Stack version 5.20b or earlier. All new projects or preexisting projects undergoing updates should be developed with the MRF24WB0 instead. 3. The WiFi connection management state machines now run on the MRF24WB0 instead of the PIC host, freeing up code and data space. Connection profiles can be created and the connection algorithm fine-tuned by the PIC application. In the WiFi demos see the WF_Connect function in MainDemo.c for an example of how to configure and then establish a WiFi connection. The programming model has changed to an API model which is documented in 'TCPIP Stack Help.chm'. 4. Changed "VERSION" macro definition in TCPIP.h to "TCPIP_STACK_VERSION". "VERSION" is overly generic and will likely conflict with other identical tokens one may use in their application code or source libraries. 5. Added support for the PIC24FJ256GA110, PIC24FJ256GB110 and PIC24FJ256GB210 PIMs for the Explorer 16. Note that when using the PIC24FJ256GA110 general purpose PIM, the Ethernet PICtail Plus, Fast 100Mbps Ethernet PICtail Plus, MRF24WB0MA Wi-Fi PICtail Plus, or other SPI PICtail daughter board should be installed in the middle SPI2 slot of the Explorer 16, not the ordinary topmost SPI1 slot used by other PIMs, including the PIC24FJ256GB110 and PIC24FJ256GB210 ones. The software is set up to use SPI2 for the PIC24FJ256GA110 PIM to avoid incompatibilities with silicon revision A3, which does not allow the SCK1 pin to be configured as a PPS output. 6. Added support for the PIC24FJ256DA210 Development Board. 7. Added TFTPUploadRAMFileToHost ( see page 502)(), TFTPUploadFragmentedRAMFileToHost ( see page 501)() and TFTPGetUploadStatus ( see page 500)() APIs to the TFTPc.c file. These APIs provide a very simple means of uploading a whole file to a remote TFTP server without requiring a great deal of application state machine logic. These 13
3
Microchip TCP/IP Stack Help APIs require the DNS client module to be enabled (STACK_USE_DNS must be defined, in addition to STACK_USE_TFTP_CLIENT). 8. Added a dummy DNS Server module. This server always sends the local IP address in response to all queries received. When using the PIC DHCP server, its purpose is to allow a user to type anything into a web browser (ex: http://asdf/) and still receive the web page provided by the PIC, much as a hotel or airport WiFi router will serve to you before you've paid or agreed to the network's terms of service. This DNS server module is implemented in DNSs.c, requires one UDP socket, and is enabled via the STACK_USE_DNS_SERVER option in TCPIPConfig.h. 9. Changed SPIFlash.h file defaults to target an SST SPI Flash with 4096 byte sectors instead of a Spansion Flash with 65536 byte sectors. These new defaults are, among other reasons, in support of the PIC24FJ256DA210 Development Board, which has an SST SST25VF016B on it. 10. Made TCP Keep-Alive packets consistently get sent TCP_KEEP_ALIVE_TIMEOUT ( see page 480) (default 10 seconds) after the last socket TX or RX activity. In earlier stack versions, if the local node transmitted some data and then let the socket go idle, the first Keep-Alive packet sent would use the TCP_START_TIMEOUT_VAL ( see page 483) (default 1 second) timer value before getting sent. While benign in terms of application behavior, these faster than normal keep-alive transmissions were distracting when viewed in Wireshark or other packet capture tools. 11. Disabled STACK_USE_DYNAMICDNS_CLIENT option in TCPIPConfig.h by default for the TCPIP Demo App and TCPIP ENCX24J600 Demo App projects. This option was enabled by default in earlier stack releases. This was done to save code size and allow out-of-box compilation on devices with 128KB of Flash when not using compiler optimizations. The TCPIP PIC32 ETH Demo App project continutes to have this option enabled by default. 12. Added SNMP v2 TRAP PDU format. Macro SNMP_STACK_USE_V2_TRAP is used to enable the SNMP v2 trap format. New API function SNMPV2TrapDemo() is included to support more than one variable binding to the SNMPv2 TRAP. This API can be used for a single SNMPv2 TRAP variable varbind and is part of CustomSNMPApp.c. A multiple variable binding demo can be enabled MainDemo.c. One should not enable both SNMPTrapDemo and SNMPV2TrapDemo simultaneously. Global flag "gSetTrapSendFlag ( see page 321)" is used to indicate the start and end of SNMPv2 trap varbinds. If gSetTrapSendFlag ( see page 321) is FALSE, then very next variable varbind for the SNMPv2 TRAP, is the last or only one variable varbind. If gSetTrapSendFlag ( see page 321) is TRUE, then there is another variable varbind available to be part of the SNMPv2 TRAP PDU. 13. Added support for PIC32MX6XX/7XX external PHY's: SMSC 8700LAN and National DP83640. 14. Added schematics and BOM for the PIC32 Ethernet Starter Kit. 15. Added the Google PowerMeter demo project. Consult the "Reference Implementation for Google PowerMeter.chm" help file for more information. 16. Modified the SSL and TCP modules to create the TCPStartSSLClientEx ( see page 469) function. This function will enable the SSL module to store supplementary data (currently only SSL Certificate Public Keys) in a structure. 17. Moved the HTTP_PORT ( see page 251), HTTPS_PORT ( see page 258), HTTP_MAX_DATA_LEN ( 251), and HTTP_MIN_CALLBACK_FREE ( see page 251) macros from HTTP2.c to TCPIPConfig.h.
see page
Fixes: 1. The SPIFlashEraseSector() function in the SPIFlash.c file incorrectly erased the sector specified by the current write pointer (set by calling SPIFlashBeginWrite()) instead of the specified dwAddr parameter address. This error had no impact on any TCP/IP Stack code as these parameters always matched. However, application code using the API would have been affected. Thanks go to Marc Boon for reporting this issue on the Microchip Ethernet forum. 2. Fixed ENC424J600/624J600 driver for PSP modes 2, 4, 6, and 10. The PIC's PMP PMMODE bits were not set correctly. 3. Removed from lingering references to TickGetDiff() in FTP.c, TFTPc.c and UARTConfig.c. 4. Fixed DNS client module from returning the DNS server IP address if the DNS query failed due to a server error (i.e. DNS did respond, but did not return any records, such as when attempting to resolve a name that isn't in the DNS). DNSIsResolved ( see page 184)() will now return 0.0.0.0 on any non-recoverable DNS error or timeout. 5. Fixed HTTP2 MPFS upload page being accessible from URLs that weren't an exact match. For example, in 5.20 and earlier, accessing http://mchpboard/mpfsuploadASDF would still have opened the mpfsupload page. Thanks go to Andrea Rivolta on the Microchip Ethernet Forum for identifying this error. 6. Improved UDP TX checksum code for the special case when the computed checksum was 0x0000. According to the UDP RFC, for this corner case, the checksum should be converted to 0xFFFF before transmission to differentiate from the checksum disabled case, improving error detection by a minuscule amount. 7. Fixed GetCLKOUT() function in ENCX24J600.c driver file. Previously, 0x00 would always be returned, regardless of the value in the COCON bits of ECON2. The function documentation for SetCLKOUT() and GetCLKOUT() was also corrected (had obsolete information ported over from ENC28J60 driver file). 14
3
Microchip TCP/IP Stack Help 8. Fixed DHCP client rebinding bug in which the DHCP client would request the wrong IP address if an unrelated DHCP OFFER or ACK message were received after we transmitted a DHCP REQUEST but before we received our DHCP ACK. Under rare conditions, this would have resulted in the TCP/IP stack reverting to the static or AutoIP assigned address for a few seconds between DHCP lease renewals. 9. Fixed TFTP Internet Bootloader bug in which uncommon .hex files containing a certain data pattern could not be uploaded correctly to the PIC18F97J60 family device. For these problem .hex files, a block of 32 program words (64 bytes) would remain unprogrammed (left as 0xFFFF) due to a parsing error in the bootloader's DecodeHex() function. The TFTP upload operation would succeed without reporting a programming error. The problem can be detected by using an ICD3 or similar ICSP programmer and reading the program Flash out of a device that is programmed with the bootloader and application .hex files. Compare the resulting memory dump to a device programmed only with the application .hex file. If you have devices deployed in the field with the previous bootloader and happen to generate a problem application .hex file, you can potentially work around the bootloader bug by opening the application .hex file with Notepad and appending dummy address records to the beginning to move the data around in the file. For example, at the very top of the .hex file, add lines containing ":020000040000FA" until the bootload process works correctly. You may alternatively try adding spaces at the end of any line, although this may make the .hex file incompatible with some programming utilities. Thanks go to Jonathan Seidmann for identifying and reporting this bug. 10. Fixed SNMPv2 TRAP format issue where SNMP browser was displaying all the SNMPv2 traps as SNMP version 1. SNMP v2 TRAP pdu format is rectified. Macro SNMP_STACK_USE_V2_TRAP is used to form and send a SNMPv2 TRAP PDU. SNMPTrapDemo API is used for both SNMPv1 and SNMPv2 single variable varbind trap. 11. Fixed an HTTP2.c server module initialization bug when using the PIC32MX7XX/6XX series internal Ethernet module. During initialization the HTTPLoadConn ( see page 256)() function would overwrite over 100 bytes of PIC RAM past the end of the reserved memory allocated for the HTTP2 module. This problem would manifest itself by locking up the TCPIP PIC32 ETH Demo App-C32 demo shortly after power up if you compiled TCP/IP Stack version 5.20 with the MPLAB C Compiler for PIC32 MCUs (C32) version 1.11. 12. Fixed SSL client from incorrectly parsing for the server's public key in rare cases where the RSA Public Key Algorithm identifier was received, but the key hadn't been received by TCP yet. Thanks go to Kevin Maimdnet for identifing this error in SSL.c and reporting it via http://support.microchip.com/. 13. Fixed Tick.c TickGet ( see page 516)(), TickGetDiv256 ( see page 516)() and TickGetDiv64K ( see page 517)() APIs sometimes returning the wrong value on PIC32 platforms. On the PIC32MX3XX/4XX family devices a wrong return result would sometimes occur if using -O3 compiler optimizations (maximum speed) with the Microchip MPLAB C Compiler for PIC32 MCUs (C32). On the PIC32MX5XX/6XX/7XX family devices, such as the PIC32MX795F512L device used on the PIC32 Ethernet Starter Kit, wrong values could be returned, regardless of the compiler optimization level. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. HI-TECH PICC-18 compilers are not supported in this release. The supplied HI-TECH PICC-18 MPLAB projects usually will not compile and/or link. 4. LCDBlocking.c timing for the LCD_E_IO enable signal is too fast to meet published data sheet limits for various LCD controllers when compiling for a PIC32 running at > 43MHz. Despite this potential timing violation, the LCD does normally work correctly on the precompiled PIC32 demos for the Explorer 16 at 80MHz.
****** v5.20 18 November 2009 ****** Changes: 1. Added PIC32MX7XX/6XX Family integrated Ethernet controller support. The "TCPIP PIC32 ETH Demo App" folder was added to compile for the PIC32 Ethernet Starter Kit. Ethernet driver files "ETHPIC32ExtPhy.c" and "ETHPIC32IntMac.c" were added, in addition to the "ETHPIC32ExtPhyDP83848.c" file, which is a specific driver file for the National DP83848 15
3
Microchip TCP/IP Stack Help 10/100 PHY. 2. Added RFC 3927 Auto IP module. This module will automatically assign a local IP address to the node in the 169.254.xxx.xxx private address range (subnet mask 255.255.0.0) if a DHCP server is not present on the network or the DHCP client is disable. The exact IP address chosen will be pseudo-random, but as required by the protocol, it will perform gratuatous ARPs to avoid clobbering anyone else's IP address. Also, unless there is an address collision with a preexisting node on the network, the IP address generated by the Auto IP module will not change between power cycle events (random number generator is seeded by local MAC address). To enable this module, STACK_USE_AUTO_IP must be defined in TCPIPConfig.h. When compiled in, the module defaults to enabled, but will automatically yield to the DHCP client module, which has higher priority. 3. Added "TCPIP MDD Demo App" beta application projects. Projects in this folder store the HTTP2 web pages in external FAT16/FAT32 formatted SD card or USB Mass Storage media instead of an MPFS2 formatted EEPROM or SPI Flash. For more information on these projects, see the "Running the TCPIP MDD Demo App (Beta Release).pdf" file in the MicrochipHelp folder. 4. Expanded XEEReadArray() API's third length parameter from a BYTE to a WORD. 5. Converted all variable declarations and type casts of TICK data type to DWORD. The TICK typedef is now deprecated and will be removed in a future stack release. This data type conflicts with the TICK structure used in certain other Microchip software libraries. 6. Added TCP_WINDOW_UPDATE_TIMEOUT_VAL ( see page 478) option to the TCP.c file (default 200ms). This timeout controls the time after calling TCPGet ( see page 450)() or TCPGetArray ( see page 451)() before the stack will transmit a RX window update to the remote node. Historically, the TCP_AUTO_TRANSMIT_TIMEOUT_VAL ( see page 478) value was used for this purpose (default 40ms). This change decreases the net window update transmission overhead. If this adversely affects your application RX performance (unlikely, but possible for certain communications patterns), set TCP_WINDOW_UPDATE_TIMEOUT_VAL ( see page 478) equal to or shorter than TCP_AUTO_TRANSMIT_TIMEOUT_VAL ( see page 478) to get the same or better behavior relative to previous stack versions. 7. Split TCP_MAX_SEG_SIZE configuration constant in TCP.c into separate TCP_MAX_SEG_SIZE_TX ( see page 481) and TCP_MAX_SEG_SIZE_RX ( see page 480) configuration constants. Previously, TCP_MAX_SEG_SIZE was used to limit both the maximum size of transmit and receive packets. In cases where large TX FIFOs are allocated, and the remote node advirtises a large Maximum Segment Size TCP option, this change improves TCP transmit performance by roughly 10%. 8. Renamed "Internet Radio App", "Internet Bootloader App" and "WiFi Iperf App" folders to "TCPIP Internet Radio App", "TCPIP Internet Bootloader App" and "TCPIP WiFi Iperf App" respectively. These new names ensure consistent folder placement when viewing the Microchip Solutions folder with other Microchip Application Libraries installed. Fixes: 1. Fixed SSL functionality (ex: HTTPS server) from failing when using the ENC424J600 and ENC624J600 Ethernet controllers. In stack versions 5.00 and 5.10, the BFSReg() and BFCReg() functions were being incorrectly used to set and clear CRYPTEN (EIR). ENC424J600/624J600 silicon errata #6 on production silicon revision A2 prevents BFSReg() and BFCReg() from being able to modify CRYPTEN. This resulted in the SSL RSA encrypt/decrypt operations from ever finishing. The ENC424J600/624J600 errata #6 workaround is now implemented in the ToggleCRYPTEN() function in ENCX24J600.c. 2. Fixed an RSA padding error in the ENCX24J600.c's version of RSASetData() and RSASetE() functions. This fixes the Bad Record MAC problem when using SSL client APIs with the ENC424J600 and ENC624J600, as mentioned in the 5.10 stack release notes' Known Problems section. Although unknown at the time of release this problem also occurred in stack version 5.00. 3. Fixed DNS client from mishandling DNS responses that did not use name compression. Thanks go to Will Stone on the Microchip Ethernet forum for identifying this bug. 4. Fixed an ExtractURLFields ( see page 214)() API bug which would incorrectly parse the URLs containing other URLs. Ex: "http://www.google.com/search?q=http://www.microchip.com/" 5. Fixed TickGet ( see page 516)(), TickGetDiv256 ( see page 516)(), and TickGetDiv64K ( see page 517)() APIs from potentially returning an incorrect time value (0x10000 ticks less than it should have) on rare occasions when using a PIC32 and with compiler optimizations turned on. The Tick.c module was also revised so that the IEC0 register does not get written to via a load-modify-store operation on PIC32s so that it is now possible for other application ISR functions to write to IEC0 without risking state corruption. 6. Fixed PIC32 Starter Kit Debugger losing access to the PIC32 target when the project was run. JTAG was being disabled at run time, but the PIC32 Starter Kit Debugger requires JTAG to communicate with the debug executive. JTAG is now conditionally disabled on PIC32s when the __MPLAB_DEBUGGER_PIC32MXSK macro is undefined. 7. Fixed a Berkeley sockets API bug in which calling closesocket (
see page 168)() on a SOCK_STREAM (
see page 16
3
Microchip TCP/IP Stack Help 175) type socket (TCP) did not actually close the socket if the remote node did not first send a FIN to the local node. This would leak a TCP socket each time the affected API calling sequence occurred and result in no FIN getting transmitted to the remote node. 8. Fixed an HTTP2 filename parsing bug that would occur when a web browser submitted a request for a file with hex encoded characters in it. For example, with stack version 5.10 and Firefox 3.5.3, typing "http://mchpboard/%70rotect" into the URL field would have resulted in an HTTP 404 not found error when "http://mchpboard/protect/index.htm" should have been returned instead. Thanks go to Steve Tuttle for reporting this issue and suggesting a solution. 9. Fixed a Berkeley sockets API bug in which calling recvfrom ( see page 173)() on a datagram type socket (UDP) would return an incorrect remote IP address and port number when the from pointer was non-NULL. 10. Fixed HTTP2 server bug in which the HTTPReadPostName ( see page 244)() function was failing to convert the field name from URL encoding to plain-text. If the browser posted, for example, a field named "Stock Remaining", it would have been incorrectly returned from HTTPReadPostName ( see page 244)() as "Stock+Remaining". 11. In Stack 5.10, any new values you saved into AppConfig via the Network Configuration demo web page would have been mishandled for WiFi projects. HTTPPostConfig ( see page 90)() in CustomHTTPApp.c of the TCPIP WiFi Demo App and TCPIP Iperf Demo App projects were corrected so that they now write a magic 0x61 marker into EEPROM/SPI Flash address 0x0000 to inidicate that the AppConfig structure is valid in EEPROM/SPI Flash. This prevents the InitAppConfig() function in MainDemo.c from restoring the default settings when changing the values through the Network Configuration page. 12. For WiFi projects, a Gratuitous ARP Work-around was implemented to work around cases where access points send broadcast messages at data rates that the ZG2100 cannot listen ( see page 172) to. The define USE_GRATUITOUS_ARP (in TCPIPConfig.h) turns this feature on or off. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. HI-TECH PICC-18 compilers are not supported in this release. The supplied HI-TECH PICC-18 MPLAB projects usually will not compile and/or link. 4. ENC624J600 PSP modes 2, 4, 6, and 10 do not work at this time. Some Parallel Bit Bang modes may not work either. Some minor firmware changes are needed. 5. TCPIP ENCX24J600 Demo App-C18.mcp project does not compile by default using MPLAB C Compiler for PIC18 MCUs (C18) version 3.34. There is not quite enough program memory available on the PIC18F97J60 for the large number of selected stack features to allow linking. To get this project to compile, turn on compiler optimizations or disable one of the modules in TCPIPConfig.h (ex: comment out STACK_USE_DYNAMICDNS_CLIENT).
****** v5.10 29 July 2009 ****** Changes: 1. Added SSL capability to the Telnet ( see page 485) server. If STACK_USE_SSL_SERVER is defined, the Telnet ( see page 485) server will now listen ( see page 172) on port 992 for SSL secured connections. If you do not have a telnets client, you can use an SSL proxy, such as stunnel (http://www.stunnel.org/) to add SSL/TLS support to any telnet client. 2. Moved a number of string pointer tables in the HTTP.c, HTTP2.c, FTP.c, and DynDNS.c files to allocate in ROM instead of RAM. This reduces around 120 bytes of RAM usage in the HTTP2 server when compiled for the PIC18 or PIC24/dsPIC platforms. The gains are even greater on PIC32 platforms. 3. Added redefinition of SPIRAM*(), SPIFlash*(), and XEEPROM*() functions so that when compiled and used without proper HardwareProfile.h definitions, a more descript linker error will be generated instead of a mysterious symbol not found error. 17
3
Microchip TCP/IP Stack Help 4. Added several new APIs: • ExtractURLFields ( see page 214)() in Helpers.c. This function provides an easy means of parsing an URL string and extracting the protocol, hostname, port, file path, etc. Currently, this function is commented out to save code space as no stack modules require it. However, it should work correctly if you simply uncomment it (remove the #if 0...#endif around it). • strnchr ( see page 222)() in Helpers.c. Finds the first occurrence of a character within a string but limited to a maximum length before giving up. • TCPPeek ( see page 457)() and TCPPeekArray ( buffer without removing the data from the stream.
see page 457)() in TCP.c. Reads from a TCP socket's RX FIFO
• TCPClose ( see page 445)() in TCP.c. Disconnects a socket from the remote node (if connected) and closes the socket handle, including for server type sockets. This function is identical to the TCPDisconnect ( see page 446)() API except for the handling of server sockets. TCPDisconnect ( see page 446)() returns server sockets to the listning state and maintains the socket handle. TCPClose ( see page 445)() closes the socket and frees all associated resources, invalidating the socket handle. 5. Updated the DHCP client module: • Modified so that it wouldn't attempt to transmit DHCP Discover packets when the MAC layer reports no link (MACIsLinked() == FALSE). This avoids main() while(1) loop performance degredation when you unplug the Ethernet cable or lose association to your access point. • Added capability of performing DHCP discovers and requests without setting the BOOTP broadcast flag. Now, the DHCP client module will start up and attempt to obtain an IP address with the broadcast flag set, but if it fails the next DHCP retry will attempt to obtain the IP address with the broadcast flag cleared. The flag will toggle back and fourth between unicast mode and broadcast mode if no DHCP server responds. This feature improves compatibility with certain DHCP servers and WiFi access points. • Added several new APIs including DHCPInit(), DHCPIsEnabled(), DHCPStateChanged(), DHCPIsBound(), and DHCPIsServerDetected(). • Removed the DHCPFlags DHCP_CLIENT_FLAGS global variable. Use the above named APIs now to get equivalent functionality. • Removed the DHCPBindCount global variable. To detect if the DHCP state has changed, poll the new DHCPStateChanged() function. • Removed the DHCPReset() API. To perform this operation, now call the DHCPInit() API. Use 0x00 for the vInterface parameter. 6. Removed deprecated TickGetDiff() macro. To get a tick difference, just subtract the two values in-line. This macro was removed because it promoted confusing code. Ex: a-b is different from b-a. However, it was not contextually obvious which of the two was returned when TickGetDiff(a, b) was called. 7. Added PIC32MX460F512L USB and dsPIC33FJ256GP710 PIM support to the Explorer 16 hardware profile for the TCPIP WiFi Demo App and WiFi IPerf App projects. 8. Added all files needed for SSL (assuming the crypto libraries are present) to the TCPIP WiFi Demo App-C30 and TCPIP WiFi Demo App-C32 projects. 9. Converted TCPIP Demo App, TCPIP WebVend App, Internet Radio App, and Internet Bootloader App MPLAB Build Directory Policy to compile in the project folder instead of the source folder. This reduces the depedancies on the MPLAB project include path and allows new projects to be created by copying one of the pre-existing folders (ex: copy "TCPIP Demo App" to "My App") without having problems including the wrong HardwareProfile.h and TCPIPConfig.h files. 10. Changed EEPROM/SPI Flash AppConfig record valid flag from 0x60 to 0x61 in the TCPIP WiFi Demo App and WiFi Iperf App projects. This will force the various EEPROM settings to get erased when switching between Ethernet and WiFi projects. This is done since the AppConfig structure changes when using WiFi (SSID string is added). 11. The Wifi Iperf App and TCPIP WiFi Demo App projects have been optimized for better performance. Fixes: 1. Fixed a TCPDisconnect ( see page 446)() API bug in which the last few bytes of data (up to the TCP socket's TX FIFO size less 532 bytes) was not transmitted and no FIN was sent out if the TX FIFO was full of data when TCPDisconnect ( see page 446)() was called. This problem could have only occurred for TCP sockets with a large TX FIFO (>=532 bytes). This problem could have been observed in stack version 5.00's "TCPIP Demo App-C32 EXPLORER_16 32MX360F512L ENC624J600 PSP 9.hex" precompiled application, among others, if you connected to the TCPPerformanceTest.c module and then attempted to simultaneously access the web server. The web server was returning data very slowly and failing to send the last parts of each file requested by the browser.
18
3
Microchip TCP/IP Stack Help 2. Eliminted a potential buffer overflow vulnerability from the HTTPHeaderParseContentLength ( see page 254)() function in HTTP2.c. If an oversized or malformed Content-Length header is sent from the web client, the function will now gracefully fail by returning an HTTP 400 Bad Request error page. Thanks go to Mark Philipp for identifying this error and suggesting a solution. 3. Fixed a TCPOpen ( see page 455)() problem in which the stack would continuously flood the network with nearly back-to-back ARP query packets if a client socket was created that specified a non-reachable remote IP address (ex: local gateway was offline, or for destinations on the same subnet, the actual remote node was offline). This problem would occur only after a few minutes (1Mbyte/sec). 7. Added multiple connection support to Telnet ( see page 485) server example module. To allow multiple connections, define MAX_SIMULTANEOUS_CONNECTIONS in Telnet.c greater than 1 and create an equal number of TCP_PURPOSE_TELNET type TCP sockets in the TCPSocketInitializer[] definition in TCPIPConfig.h. 8. Added more randomness to the local port selection when opening a client-mode TCP socket. This reduces the risk of reusing a previously used port number if the user power cycles the device. 9. Updated XEE* SPI EEPROM API functions. Writes are no longer required to start on an EEPROM page boundary, and writes can now be arbitrarily long without having to call XEEEndWrite() at each page boundary. Additionally, the XEEWriteArray() API has been added, which performs a similar operation to the SPIFlashWriteArray() API (but with no special erase cases to worry about). 10. Decoupled AppConfig storage in external SPI EEPROM or SPI Flash option from MPFS_USE_EEPROM and MPFS_USE_SPI_FLASH options. MainDemo.c will now save the AppConfig structure in external non-volatile memory, even if MPFS is unused (no HTTP or SNMP server modules enabled) or MPFS is using internal Flash program memory to store web pages/bib information. This change also allows the XEE*() and SPIFlash*() non-volatile read/write functions to be available at all times (even if MPFS is unused), as long as the appropriate hardware pinout definitions are present in HardwareProfile.h. SPI Flash and SPI EEPROM are no longer mutually exclusive with each other. However, if both are enabled simultaneously, AppConfig will be stored in the EEPROM, not the SPI Flash. 11. Added required SSL files to TCPIP Demo App MPLAB projects. SSL capabilities can now be turned on directly via the STACK_USE_SSL_SERVER and STACK_USE_SSL_CLIENT options in TCPIPConfig.h for these projects, assuming appropriate crypto libraries are installed (SW300052 available from https://www.microchipdirect.com/). With this change, the historical "SSL Demo App" folder has been removed. 13. Updated HardwareProfile.h files. This includes the addition of PIC18 Explorer board support, removal of the PICDEM Z profile, changes to the HI-TECH PICC-18 profiles for newer compilers, among other changes. 14. Added a TCP and UDP performance test measurements table to TCPIP Stack Help (TCPIP Stack Help.chm). Access this from the "Microchip TCP/IP Stack" book, "Stack Performance" page. 15. Updated MPFSlib project (Microchip.MPFS.dll file) so that C18 and C32 output from the MPFS2.exe utility is now identical for MPFS2 images. The generated .c file is now compatible with both C18 and C32 compilers simultaneously. Previously, the images generated for C18 would compile successfully for C32 projects, but would potentially operate incorrectly when compiler optimizations were turned on. Images generated for C32 would compile successfully and work on C18 projects, but the C18 compiler would take a very long time to process the file each time you rebuilt your MPLAB project. Now, the image generated for C18 matches the image generated for C32 and it will compile fast and work correctly on both platforms, even with compiler optimizations turned on. 16. Added schematics and BOMs for the Ethernet PICtail, Ethernet PICtail Plus, Fast 100Mbps Ethernet PICtail Plus, Internet Radio, PICDEM.net 2, and ZeroG ZG2100M PICtail development boards to the "MicrochipTCPIP StackDemo Board Files" folder. Fixes: 20
3
Microchip TCP/IP Stack Help 1. Fixed a denial of service vulnerability in the NBNSGetName ( see page 288)() function of the NBNS.c file. Previously, if a deliberately malformed packet was received, the PIC RAM could have become corrupted. Thanks go to David Talmage for finding this vulnerability. 2. Fixed Timer1 interrupt flag clearing code on PIC32 products. Previously, the Tick.c module was clearing the interrupt flag in an unsafe manner which could have corrupted other interrupt flags in the IFS0 register. Thanks go to Leon van Snippenberg working on the AVIX-RT RTOS for pointing this error out on the Microchip forums. 3. Fixed SNMP up-time variable. Previously the CustomSNMPApp.c module would respond with the number of Tick API ticks that elapsed, not the number of 10ms time slices that elapsed. The SNMP standard uses 10ms as its time base. 4. Fixed BigInt_helper.asm's _masBI() and _masBIROM() functions when the Br parameter's length modulo 4 was equal to 1 or 2. This bug previously caused the BigIntMod() function to sometimes go into an endless calculation loop on PIC18 products when using the SSL libraries and certain combinations of modulus data and length were used. Thanks go to Vasil Stoianov on the Microchip Ethernet forum for running into this defect and reporting it. 5. Fixed SSLSessionNew ( see page 429)() so that it wouldn't "lose" SSL sessions after waiting a few hours. This would previously make it impossible to make new SSL connections after a while, but then after a few more hours, the sessions would become free again. Thanks go to Jim Stephens for identifying this issue and finding the solution. 6. Fixed an SSL 2.0 antique client hello record length calculation bug occurring when a received record was > 255 bytes. 7. Added retransmission capability to SendNotification ( see page 113)() function in CustomSNMPApp.c. Previously, if an SNMP trap were sent, but the initial ARP query or response was lost on the network, the SendNotification ( see page 113)() code would have deadlocked, and suppressed all future transmission of SNMP traps. 8. Fixed DNS client timeout if the DNS server is unable to be ARPed. Previously, the DNS client would retry ARPing the DNS server indefinitely if it was offline. Now, the DNS client will correctly abort if too many attempts to ARP the DNS server fail. Thanks go to Phil "andersop" on the Microchip Ethernet forum for identifying this error. 9. Suppressed transmission of a TCP RST packet to an unknown IP or MAC address if the TCPDisconnect ( see page 446)() function was called on a client mode socket that was not finished with ARP or DNS resolution yet. Thanks go to Phil "andersop" on the Microchip Ethernet forum for pointing this behavior out. 10. Fixed TCP socket from disconnecting if the remote receive window was zero and TCPFlush ( called. Thanks go to Bob Topper for identifying this issue and suggesting a solution.
see page 450)() was still
11. Fixed Tick.c module returning incorrect values when TickGet ( see page 516)() or other API was used with compiler optimizations turned on. Wrong values were observed when using MPLAB C Compiler for PIC24 MCUs and dsPIC DSCs version 3.12. 12. Fixed a number of SPI communications problems that could occur when compiler optimizations were turned on. The ENC28J60 was observed to not work correctly on the dsPIC33FJ256GP710 processor when compiled with MPLAB C Compiler for PIC24 MCUs and dsPIC DSCs version 3.12. 13. Fixed possible MPFS2 error when using an ASM30 .s image where MPFS_Start would be read using the wrong PSVPAG setting. You must rebuild your MPFS2 image file (ex: MPFSImg2.s) with this stack version's MPFS2.exe utility to get this correction applied. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. HI-TECH PICC-18 compilers are not supported in this release. The supplied HI-TECH PICC-18 MPLAB projects usually will not compile and/or link. 4. ENC624J600 PSP modes 2, 4, 6, and 10 do not work at this time. Parallel Bit Bang mode does not work either. Some minor firmware changes are needed.
****** v4.55 10 November 2008 21
3
Microchip TCP/IP Stack Help
****** SSL Note: RSA.c and ARCFOUR.c have not changed between the 4.50 and 4.55 releases. Although the precompiled SSL Demo App .hex files will differ, you can continue to use the previous TCP/IP Stack v4.50 Encryption Add-on with this 4.55 stack version. Changes: 1. Added DNS client support for a secondary DNS server address. Previously, the AppConfig.SecondaryDNSServer setting was unused. Now, the DNS client module will automatically swap the AppConfig.PrimaryDNSServer and AppConfig.SecondaryDNSServer values after any DNS query timeout (or ARP timeout for the DNS server) and attempt the query with the alternative server. If AppConfig.SecondaryDNSServer is disabled by setting it to the IP address 0.0.0.0, the DNS client will only use the AppConfig.PrimaryDNSServer value and never swap the values. With this change, the DHCP client was also updated. If the DHCP server does not specify a secondary DNS server, then the DHCP client will now set the AppConfig.SecondaryDNSServer value to 0.0.0.0. Previously, it would change the AppConfig.SecondaryDNSServer setting only if the remote DHCP server offered a secondary DNS server. Fixes: 1. Updated Internet Bootloader App project to correctly detect if the configuration bits are being changed or not. Previously, the bootloader always thought the configuration bits were being changed and thus had to always erase the last Flash page (largest memory address) twice for each firmware update. This did not cause any functional problems or specification violations, but it would decrease the effective Flash endurance of the last page. 2. Fixed a TCP socket memory corruption bug that would occur if TCPGetRemoteInfo ( see page 451)() API was called twice with different socket handles without an intermediate call to any other TCP API that takes a TCP_SOCKET ( see page 466) input. Thanks go to Bob Topper for identifying this problem and suggesting a solution. 3. Fixed the UDPIsGetReady ( see page 527)() function so that it returns the number of bytes remaining in the packet based on the current read location. This is the same behavior as stack versions 4.18 and earlier. In stack versions 4.50 and 4.51, the UDPIsGetReady ( see page 527)() function would always return the total number of bytes in the current packet, regardless of how many bytes the read pointer had been advanced through the UDPGet ( see page 526)() and UDPGetArray ( see page 527)() functions. Thanks go to Bob Topper for identifying this problem and suggesting a solution. 4. Fixed demo admin web page in TCPIP Demo App project so that the last byte of the MAC address can be changed, independent of the format it was entered by the user. 5. Fixed a buffer overflow bug that would occur when using the SSL server during hashing of the server certificate for the initial handshake. This error previously caused several bytes of random variables elsewhere in the project to get overwritten for each SSL connection. 6. BSD sockets API was updated to fix some issues. 7. LCDBlocking.c was updated to relax start up timing. This timing fix is specifically needed to support Explorer 16 boards with a Truly TSB1G7000 display (Novatek NT7603H controller). 8. Removed four uses of Arial Black font in MPFS2.exe utility. On some rare PC configurations, the use of this font caused the executable to not run. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail. 4. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate TCP_ETH_RAM_SIZE or MAX_HTTP_CONNECTIONS. 5. HI-TECH PICC-18 STD 9.51PL1 cannot compile DynDNS.c. It raises an "inconsistent type" error while trying to perform a ROM pointer to integer cast. The older 9.50PL3 compiler release is required to compile this file. 6. HI-TECH PICC-18 STD 9.50PL3 does not initialize several static variables correctly on reset. This behavior breaks many 22
3
Microchip TCP/IP Stack Help stack modules in the TCPIP Demo App and TCPIP WebVend App projects. Additionally, string printing functions do not work correctly, so the supplied "TCPIP Demo App-HITECHPICC18 PICDEMNET2 18F97J60.hex" and "TCPIP WebVend App-HITECHPICC18 PICDEMNET2 18F97J60.hex" files may not correctly print the board's DHCP assigned IP address on the board's LCD (if present) and UART. To avoid these severe problems, use the Microchip MPLAB C Compiler for PIC18 MCUs. A free student edition can be downloaded from http://www.microchip.com/c18.
****** v4.51 24 July 2008 ****** IMPORTANT NOTE: You must use MPLAB 8.10 or higher to successfully open the MPLAB projects. SSL Note: RSA.c and ARCFOUR.c have not changed between the 4.50 and 4.51 releases. Although the precompiled SSL Demo App .hex files will differ, you can continue to use the previous TCP/IP Stack v4.50 Encryption Add-on with this 4.51 stack version. Changes: None. This release includes bug fixes only. It is very important that applications using the ENC28J60 get fix item 7, below. Fixes: 1. TCPOpen ( see page 455)() was previously failing if you used it to start a connection with a remote hostname, but the DNS module failed to resolve the remote address on the first try. This, for example, would occur if you powered up your board and tried to connect ( see page 168) to a remote server before the Ethernet cable was attached. Once the Ethernet cable was attached, the socket would attempt to resolve and connect ( see page 168) to a garbage address. The Internet Radio application would sometimes not begin playing the default station upon power up because of this problem. 2. Set SEQ.ACK = 0 for outbound TCP SYN packets. This fixes a connection compatibility problem with certain paranoid TCP/IP stacks that would validate this field even though the ACK flag was clear. This problem would previously cause the Microchip TCP/IP stack to be unable to connect ( see page 168) client-mode TCP sockets to certain rare servers/services. Thanks go to Jean LE TUTOUR for finding one of these problem servers. 3. MPFSOpen ( see page 278)() and MPFSOpenROM ( see page 279)() for MPFS2 could leak a file handle if a name hash matched but no complete file name did. This has been corrected to prevent potential DOS attacks on the HTTP2 web server. Thanks to David Tan on the Microchip Ethernet formus for identifying this issue. 4. Fixed a bug in MPFS2.1 that caused compile errors when MPFS Classic images were generated for ASM30 containing files whose length was either zero or a multiple of 12. 5. Fixed an issue in HTTPPostConfig ( see page 90)() that caused it to ignore the flag that was set when invalid IP address input was detected. This issue only affects the example configuration page and only exists in v4.50 (prior versions functioned correctly). Also corrected an issue where user input could potentially overflow into part of the shadow AppConfig in the same function. Thanks to prinz3nroll3 on the Microchip Ethernet forums for identifying both of these issues. 6. Implemented Explorer 16 development board 5V LCD errata workaround to LCDBlocking.c. This corrects the A/D converter from returning erratic readings on certain Explorer 16 boards. LCD I/O pins are now continuously driven by the microcontroller instead of going high impedance when idle. 7. Fixed a critical ENC28J60 revision B7 errata workaround problem in the ENC28J60.c, MACFlush() function. Previously, the code was checking for an EREVID register value of 0x07 for silicon revision B7. This was incorrect. Silicon revision B7 actually has an EREVID value of 0x06. Note that this problem was caused by an incorrect EREVID value published in DS80349A, the B7 silicon errata documentation. Make sure to use DS80349B or later. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 23
3
Microchip TCP/IP Stack Help 3. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail. 4. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate TCP_ETH_RAM_SIZE or MAX_HTTP_CONNECTIONS. 5. HI-TECH PICC-18 STD 9.51PL1 cannot compile DynDNS.c. It raises an "inconsistent type" error while trying to perform a ROM pointer to integer cast. The older 9.50PL3 compiler release is required to compile this file. 6. HI-TECH PICC-18 STD 9.50PL3 does not initialize several static variables correctly on reset. This behavior breaks many stack modules in the TCPIP Demo App and TCPIP WebVend App projects. Additionally, string printing functions do not work correctly, so the supplied "TCPIP Demo App-HITECHPICC18 PICDEMNET2 18F97J60.hex" and "TCPIP WebVend App-HITECHPICC18 PICDEMNET2 18F97J60.hex" files may not correctly print the board's DHCP assigned IP address on the board's LCD (if present) and UART. To avoid these severe problems, use the Microchip MPLAB C Compiler for PIC18 MCUs. A free student edition can be downloaded from http://www.microchip.com/c18.
****** v4.50 02 June 2008 ****** IMPORTANT NOTE: You must use MPLAB 8.10 or higher to successfully open the MPLAB projects. Also, ensure that the latest C compiler is used. This release was tested against MPLAB C Compiler for PIC18 MCUs version 3.20, MPLAB C Compiler for PIC24 MCUs and dsPIC DSCs version 3.10, MPLAB C Compiler for PIC32 MCUs version 1.01, and HI-TECH PICC-18 version 9.50PL3 (STD). Earlier compilers may not be able to compile this TCP/IP stack release. Changes: 1. Added SSL 3.0 client capabilities, including SMTP over SSL. The SSL modules supports up to 1024-bit RSA handshakes and 128-bit ARCFOUR bulk encryption. This can be demonstrated using the SMTP client. SSL server support is functional, but a key generation utility is not yet provided and support over HTTPS is not yet reliable with all browsers. IMPORTANT: Encryption software is covered by US Export Control law, so it is not directly downloadable from the Microchip website. To use the encryption modules, you must order SW300052 from microchipDIRECT [ https://www.microchipdirect.com/ ] and install the required libraries. 2. Added Berkeley Sockets ( see page 149) Distribution (BSD) API translation layer. You can now call the well know Berkeley APIs instead of or in addition to the Microchip specific APIs. To use this new functionality, define STACK_USE_BERKELEY_API and configure BSD_SOCKET_COUNT in TCPIPConfig.h. Three new source code demos are provided to demonstrate this API: BerkeleyTCPClientDemo.c, BerkeleyTCPServerDemo.c, and BerkeleyUDPClientDemo.c. The TCP client demo is identical to the GenericTCPClient.c demo, but implemented using Berkeley Sockets ( see page 149). The UDP client demo is similarly identical to the SNTP.c client. The TCP server demo listens on TCP port 9764 and will echo any traffic received back to the sender. It allows up to 3 simultaneous connections when there are an adequate number of sockets defined in the TCPSocketInitializer[] array in TCPIPConfig.h. 3. Added support for Dynamic DNS services. See the Dynamic DNS Client module in the TCP/IP Stack Help for details. Presently, dyndns.org, dyndns.com, no-ip.com, and dns-o-matic.com are supported. 4. Added the Microchip TCP/IP Configuration Wizard to the Utilities folder, facilitating easier configuration of the TCP/IP Stack through a graphical application. 5. Restructured TCPIPConfig.h to remove rule-enforcement logic, placing the removed sections in TCPIP.h. Many other project structure changes were also made to clean up the general distribution appearance. 6. Increased DHCP Server default lease duration to 60 seconds instead of 15 seconds. Some computers were losing their IP lease before performing a renew operation with only a 15 second lease. 7. Removed CLOCK_FREQ, INSTR_FREQ, and PERIPHERAL_FREQ macro definitions. GetSystemClock(), GetInstructionClock(), and GetPeripheralClock() now return these respective values. This change was made for compatibility with other Microchip software libraries. 8. Added TCP Fast Retransmission capability. Whenever three duplicate ACK packets arrive, the stack will now immediately perform a retransmit operation. This greatly improves recovery latency whenever the network loses a packet for applications that stream TX data using TCP. 9. Improved TCP Keep Alive mechanism to automatically close TCP sockets which do not receive any keep-alive responses 24
3
Microchip TCP/IP Stack Help for TCP_MAX_UNACKED_KEEP_ALIVES ( see page 481) (default 6) times. This means that, by default, any connection that catastrophically breaks without notifying us (ex: user unplugs cable, Internet connection goes down, etc.) will time out and automatically close after 60 seconds (TCP_MAX_UNACKED_KEEP_ALIVES ( see page 481) * TCP_KEEP_ALIVE_TIMEOUT ( see page 480)). Server oriented sockets will return to the listening state. Client oriented sockets will close, but the TCP_SOCKET ( see page 466) handle will continue to remain valid until the application calls TCPDisconnect ( see page 446)(). Applications can check if the socket became disconnected and reset by calling TCPWasReset ( see page 462)() or TCPIsConnected ( see page 453)(). Note that this keep alive implementation will only close sockets that are broken (remote node is not responding to TCP requests). It will not close or otherwise interfere with idle connections in which the application is not transmitting or receiving data and wishes to keep the connection open. 10.Added a TCP RX SYN queue of depth TCP_SYN_QUEUE_MAX_ENTRIES ( see page 484) (default 3). This queue automatically saves incoming SYN packets destined for a local server port which is already connected to a different client. When the client disconnects, the SYN data is pulled out of the queue and the socket immediately attempts to connect ( see page 168) to the next client. This improves connect ( see page 168) time performance since the remote client no longer has to retransmit the SYN request if it was unserviceable the first time around. This is most apparent with the HTTP/HTTP2 servers which previously performed poorly with certain modern web browsers which attempt to open many simultaneous connections to the web server, such as Mozilla Firefox 3 beta 5 and Apple Safari 3.1. Entries in the queue automatically time out after TCP_SYN_QUEUE_TIMEOUT ( see page 484) (default 3 seconds) so as to prevent the queue from filling up permanently if several connection requests arrive for a service that is in use and will not be available for an extended period. 11.Modified the structure of the MPFS2 FAT (now known as MPFS2.1) to include name hashes first. This speeds up opening files by 25%, and makes opening index files nearly instant. 12.Updated the MPFS2 Utility. MPFS2.1 now supports the new FAT structure and provides a cleaner interface. It also writes images to disk as they are created, which eliminates the IndexOutOfBounds exceptions some users had reported. Finally, uploads are now truly multi-threaded. 13.Source code to the MPFS2.exe PC utility is now released. Find it in the Microchip SolutionsMicrochipTCPIP StackUtilitiesSourceMPFS21 folder. This project is designed to compile with Microsoft Visual C# 2008 Express Edition. 14.Added support for SST25VFxxxB serial flash parts in 2, 4, 8, 16, and 32Mbit densities. These parts can be used to replace EEPROMs for storing MPFS images (both versions) and custom data. 15.Added HTTPReadPostName ( see page 244), HTTPReadPostValue ( see page 245), and HTTPReadPostPair ( see page 245) functions to facilitate easier processing of data arriving via POST. 16.Split HTTPAuthenticate API into separate functions: HTTPNeedsAuth ( see page 242) and HTTPCheckAuth ( see page 238). This function was already split internally, and didn't make sense as a single API. 17.Updated DHCP client to close its UDP socket when idle (bound state) to save a small amount of resources. 18.Removed LED_IO macro from all hardware profiles because it is not suitable for use on certain hardware platforms that have non-contiguous LEDs or reversed bit ordering. Use the new LED_GET() and LED_PUT(val) macros to read and write to all of the LEDs at once. 19.Added Ethernet Hash Table Calculator.exe to the Utilities folder and start menu. This tool will calculate the correct bit that you must set in the EHT0-EHT7 registers on the ENC28J60 and PIC18F97J60 family devices for using the Hash Table RX filter. This is useful only for fixed MAC addresses known at design time. For addresses that are known at run time, use the SetRXHashTableEntry() function in the ENC28J60.c or ETH97J60.c files to set the correct EHT0-EHT7 bit. Fixes: 1. Fixed a buffer overflow data corruption issue in the FTP module that arises when too many parameters were passed on the command line. 2. Moved TCPWasReset ( see page 462) checking in HTTP2 to execute for every socket on every loop. Previously, it would only execute when a socket reconnected, which caused the RX buffer to not resize until after data was received. Some platforms (notably FF2 on Ubuntu) would stall if the initial advertised RX window was too small, and this change corrects that issue. 3. Updated SendSystemReset() and MACInit() initialization routine in ENC28J60.c. Previously, if the ENC28J60 was placed into sleep mode by calling MACPowerDown(), the SendSystemReset() command would not work anymore. This would leave the ENC28J60 in power down if the host PIC was ever reset. SendSystemReset() should work for all conditions with this update. Thanks go to Rob Haverkort on the Microchip Ethernet forum for identifying this problem. 4. Fixed an alignment bug in HTTP2 that caused redirects to fail when the MPFS2 image was stored in Flash program memory. Thanks to Todd Boaz on the Microchip Ethernet forum for identifying this bug, and Chen Qu for posting a solution. 5. Fixed SNTP client from losing accuracy if you called SNTPGetUTCSeconds ( see page 371)() 10s of thousands of times since the last server synchronization. Thanks go to "pic123" on the Microchip Ethernet forum for noticing this error. 6. Fixed a TickGet ( see page 516)*() API problem where the returned tick value could be off by 64K ticks occasionally on PIC24, dsPIC30/33, and PIC32 processors. This bug was previously fixed in stack versions 4.13 and 4.16, but it was 25
3
Microchip TCP/IP Stack Help unintentionally recreated in 4.18 due to PIC32 changes. 7. Fixed UART2TCPBridge module from failing to connect ( USE_REMOTE_TCP_SERVER was defined.
see page 168) to a remote server when
8. Fixed an issue that prevented SNMP SETs on 16 and 32 bit parts when using MPFS2. Thanks go to Milena K on the Microchip Ethernet forum for identifying this problem. 9. Fixed a rare buffer corruption issue that could occur with UDP if TCP was also enabled. 10.Fixed a Tick rollover error in HTTP2. Thanks go to Paul Bixel on the Microchip Ethernet forum for identifying this problem. 11.Fixed an MPFS2 bug in which an excessive value to MPFS_SEEK_REWIND may have failed to return an error. Thanks go to Paul Bixel on the Microchip Ethernet forum for identifying this problem as well. 12.SMTP Client now sends EHLO when using authentication. Previously, the HELO command was used, even with authentication enabled. Using HELO with authentication creates incompatibilities with certain SMTP servers. 13.Improved Internet Bootloader robustness by retransmitting ACKs in response to data retransmissions by the remote sending node. Previously, if an ACK packet was lost before reaching the sending node, the TFTP upload would fail and need to be restarted. Thanks go to "coolvibe" Dave Collier on the Microchip Ethernet forum for identifying this behavior. 14.Fixed TFTP Internet Bootloader from not being accessible from Linux TFTP clients which were setting the IP header "Don't Fragment" flag bit. 15.Changed TCP so that unsent data that is automatically flushed by the TCP_AUTO_TRANSMIT_TIMEOUT_VAL ( see page 478) timer includes the PSH flag. This improves GUI responsiveness for certain applications which rely on this automatic flush feature, such as the UART2TCPBridge module. 16.Fixed TCP socket loss issue which could occur if the TCP TX FIFO size was greater than 536 bytes (TCP_MAX_SEG_SIZE). Before the fix, the socket would have gotten tied up indefinitely performing retransmissions every 1.0 seconds without detecting that the remote node was disconnected. 17.Fixed TCP socket hang issue that would occur if the PIC sent out a FIN and the remote node never responded with a corresponding FIN. The socket would have gotten stuck indefinitely in the TCP_FIN_WAIT_2 state. Thanks go to Mr. Kyle Strickland with AW North Carolina for identifying this bug. 18.Fixed UDPSetRxBuffer ( see page 531)() function from not working if it was called before having called UDPGet ( see page 526)() or UDPGetArray ( see page 527)() at least once. 19.Fixed an offset error of +2 milliseconds being returned from TickConvertToMilliseconds ( see page 515)(). Thanks go to Andrés ("saturn") on the Microchip Ethernet forum for finding this error. Note that due to integer truncation during division, this function can be off by 0.2% or so, depending on the value returned by GetPeripheralClock(). 20.Updated DelayMs() macro for MPLAB C Compiler for PIC18s to work correctly when a large parameter was given. You should now be able to delay between 0 and 65535 milliseconds across all supported compilers without ending up with an unexpectedly short delay. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail. 4. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate TCP_ETH_RAM_SIZE or MAX_HTTP_CONNECTIONS. 5. HI-TECH PICC-18 STD 9.51PL1 cannot compile DynDNS.c. It raises an "inconsistent type" error while trying to perform a ROM pointer to integer cast. The older 9.50PL3 compiler release is required to compile this file. 6. HI-TECH PICC-18 STD 9.50PL3 does not initialize several static variables correctly on reset. This behavior breaks many stack modules in the TCPIP Demo App and TCPIP WebVend App projects. Additionally, string printing functions do not work correctly, so the supplied "TCPIP Demo App-HITECHPICC18 PICDEMNET2 18F97J60.hex" and "TCPIP WebVend App-HITECHPICC18 PICDEMNET2 18F97J60.hex" files may not correctly print the board's DHCP assigned IP address on the board's LCD (if present) and UART. To avoid these severe problems, use the Microchip MPLAB C Compiler for PIC18 MCUs. A free student edition can be downloaded from http://www.microchip.com/c18.
26
3
Microchip TCP/IP Stack Help
****** v4.18 28 November 2007 ****** Changes: 1. Added C32 and PIC32MX support. Some things were cleaned up in the process. 2. Removed linker scripts from C30 MPLAB projects. MPLAB IDE 8.00 can automatically select the correct linker script for 16-bit and 32-bit products. 3. Updated TCPPerformanceTest.c module. Now it automatically calculates the TX throughput and displays it for you. Also, there is now an RX throughput testing mode, which listens on a separate TCP socket (port 9763) when a TCP socket of type TCP_PURPOSE_TCP_PERFORMANCE_RX is allocated in TCPIPConfig.h. The RX socket is by default not enabled to save memory, so you must create a TCP_PURPOSE_TCP_PERFORMANCE_RX socket in TCPIPConfig.h and ensure that enough memory is allocated to accommodate it to test the RX performance test. When connected to port 9763, send a large amount of data and the PIC microcontroller will send back a count of how many bytes were received per second. 4. UDPPerformanceTest.c module now transmits 1024 packets on start up and then stops to prevent continually broadcast flooding your network. To transmit more packets after 1024 is reached, hold down BUTTON3 (left-most button on most boards). 5. Significantly improved the speed of the MD5 and SHA-1 functions. Gains for the 8-bit compilers were 50-75%, while 16-bit parts saw more modest improvements (~10%). 6. Reimplemented TCP_CLOSE_WAIT TCP state ("CLOSE WAIT" in RFC793). Now, TCP sockets that receive a FIN from the remote node will hold off transmitting a FIN back to the remote node until the TCP_CLOSE_WAIT_TIMEOUT ( see page 478) (defined at the top of TCP.c) elapses or immediately when the application calls the TCPDisconnect ( see page 446)() function. This makes it possible for the application to transmit a response back to the remote node before the socket becomes closed on our end. Similarly, it simplifies application usage of the last RX bytes received as these bytes are now assured to still be in the RX FIFO for at least TCP_CLOSE_WAIT_TIMEOUT ( see page 478) seconds. TCP_CLOSE_WAIT_TIMEOUT ( see page 478) defaults to 200ms in this stack version. 7. Pushed the SNTP requery on failure timeout up some. It was ~14 seconds and is now ~20 seconds. 8. Added TFTPOpenROMFile ( products.
see page 498)() API to complement TFTPOpenFile (
see page 498)() when using PIC18
9. Added a fourth parameter to newAJAXCommand() in mchp.js, allowing data to be POSTed along with the AJAX request. 10.Deprecated the TCP Loopback functions, which includes TCPOpenLoopback, TCPCloseLoopback, TCPIsLoopback, TCPInject, and TCPSteal. These functions were added in 4.10 for future SSL support, but have since become unnecessary. They are of limited usefulness, and so are being removed to save code space. The functions are still available in this version, but will be removed in the next release. 11.Added SMTPClient.ServerPort ( see page 96) field to the SMTP API. This allows the remote server port number to be specified dynamically at run time instead of being hard coded to the SMTP_PORT ( see page 311) value defined at the top of SMTP.c. SMTP_PORT ( see page 311) is now only a default. 12.Added web interface to the SMTP module in the TCPIP Demo App applications. You can now configure the SMTP module and send emails directly from within your web browser. The HTTPPostEmail ( see page 91)() function in CustomHTTPApp.c also demonstrates how to send MIME encoded attachments in emails. The default demo will send button states, LED states, and the current potentiometer reading as a CSV file attached to the email. 13.Changed SMTPDemo ( see page 94)() in MainDemo.c to trigger on BUTTON2 and BUTTON3 simultaneously held down instead of BUTTON0 only. Fixes: 1. Fixed an ENC28J60.c MACGetArray() bug which would overwrite one byte of memory at address 0xFFFFFFFF if you provided NULL for the destination address pointer. 2. Fixed an MPFS2.c MPFSGet ( see page 272)() bug which would overwrite memory address 0x00000000 if a NULL pointer was provided as the destination. 3. Fixed a bug in the HTTP2 server accessing incorrect sockets if an inadequate number of sockets were available on POR. 4. Fixed Internet Bootloader project from failing with a timeout if an ARP packet arrived during the Erase/Write operation. 5. Fixed DHCP client RFC non-compliance where it would send the ciaddr field in the initial SELECTING state. Also, in the 27
3
Microchip TCP/IP Stack Help RENEWING state, the Requested IP Address ( see page 144) option was being sent, which is illegal. These changes may fix compatibility problems with certain DHCP servers. 6. Fixed TFTP Client's TFTPCloseFile ( see page 492)() function from sending data using a wrong UDP socket if StackTsk() was called after TFTPIsFileOpened ( see page 494)() was last called. 7. Added two zero bytes to the ICMP echo request payload to improve compatibility with some buggy NAT routers. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 3. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail. 4. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate TCP_ETH_RAM_SIZE or MAX_HTTP_CONNECTIONS.
****** v4.16 06 November 2007 ****** Changes: 1. Added Internet Radio application. This is a TCP client application which downloads streaming MP3 audio from a Shoutcast server and then plays it back to stereo earphones via a VLSI VS1011 audio decoder. 2. Added SPIRAM.c module. This module is intended for interfacing to an AMI Semiconductor N256S0830HDA SPI RAM chip. The TCP module can now interface directly to this SPIRAM module to store TCP socket FIFO buffers and other TCB data in the external RAM. 3. Added TCP_OPTIMIZE_FOR_SIZE ( see page 481) compile time configuration macro to TCP.c file. When optimizing for small code size, the TCP module ROM footprint shrinks up to 6KB, but performance may slow down on some processors (namely PIC18s, where the penalty is approximately 15%). 4. Added USE_EEPROM_25LC1024 compile time configuration macro to TCPIPConfig.h. Enable this definition if you are storing your MPFS[2] on a 1Mbit 25LC1024 or similar EEPROM device that uses 24-bit addressing and a 256 byte write page size. 5. Changed LCDBlocking.c module initialization code. It should now be possible to use 4-bit mode on certain "unusual" LCD controllers, like the Samsung S6A0032. Most PICDEM.net 2 and Explorer 16 boards use an LCD with this controller. 6. SNTP client now attempts to requery the SNTP server about every 14 seconds if the last query attempt fails. This allows the internal time value to become valid quickly should the board be powered up before an Ethernet cable is attached or if the DHCP client doesn't obtain an IP address quickly enough. Previously, it would take up to 10 minutes after plugging the Ethernet cable in to get a correct time value from the SNTP server. 7. Added UDP_USE_TX_CHECKSUM compile time configuration macro to TCPIPConfig.h. When enabled, all UDP packets will have a correct UDP checksum computed and inserted into the UDP header of outbound packets. If you do not define this macro, the UDP checksum will be disabled (left as 0x0000), which is how previous stack versions operated. Note that enabling checksum generation cuts your maximum UDP TX throughput by nearly half due to the required computations. 8. Substantially changed TCP socket RX and TX FIFO allocation. Now, sockets can be stored either in Ethernet RAM, PIC RAM, or external (SPI) RAM. Previously, sockets could only be allocated in Ethernet RAM, which was not scalable. 9. Added TCPOpen ( see page 455)() API function. This replaces TCPListen ( see page 455)() and TCPConnect ( see page 445)(). TCPOpen ( see page 455)() supports a large number of options that will make the creation of client mode sockets much easier. You can specify the remote node as a hostname that needs DNS and ARP resolution, an IP address that only needs ARP resolution, or legacy NODE_INFO pointer for direct compatibility with the previous 28
3
Microchip TCP/IP Stack Help TCPListen ( see page 455)() and TCPConnect ( see page 445)() APIs. TCPOpen ( see page 455)() also supports a socket type parameter which will allow you to use the new TCP socket RAM allocation system. 10.Added TCP Keep Alive mechanism defined by RFC 1122 section 4.2.3.6 to the TCP module. This helps automatically detect lost connections. If the remote node sends back an RST, this immediately closes the lost connection on our end. Currently, no action is taken if the keep alive gets no response. Note that this feature deviates from the standard by defaulting to only 10 seconds instead of over 2 hours. Also deviating from the standard, this feature is enabled by default. To disable it, undefine TCP_KEEP_ALIVE_TIMEOUT ( see page 480) at the top of TCP.c. 11.Moved TCPPerformanceTest.c module from default port 12345 to 9762. 12.Moved UDPPerformanceTest.c module from default port 12345 to 9, the "discard" protocol port. Fixes: 1. The DHCP client now specifically requests the previous IP address when a DHCP renewal occurs. 2. The SNTP client now correctly maintains time when repetitively calling SNTPGetUTCSeconds ( see page 371)() between an NTP requery event. Thanks go to Rob Haverkort on the Microchip Ethernet forum for noticing the time value incrementing far faster than it should have. 3. TCP module will not transmit a bunch of unnecessary duplicate ACK packets when data is ready to be transmitted but the remote RX window is zero. This previously didn't cause anything to break, but would waste CPU time and bandwidth sometimes. 4. TCP sockets will no longer automatically close if the remote RX window stays zero for several seconds. 5. Fixed TFTP Internet Bootloader project from corrupting the configuration fuses. Previously, this would result in the Watchdog timer being enabled and causing an unintentional reboot every few minutes with the demo TCP/IP stack. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. TFTPc module has not been tested with this version. 3. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 4. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail. 5. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate MAX_TCP_SOCKETS, TCP_TX_FIFO_SIZE, TCP_RX_FIFO_SIZE, or MAX_HTTP_CONNECTIONS.
****** v4.13 02 October 2007 ****** Changes: 1. Added command line support to the MPFS2.exe tool. You can now generate MPFS output files using batch scripts or other console applications. 2. Added dynamic variable parameter capabilities to the MPFS2 utility. To use, add the parameters you wish to pass to the end of the dynamic variable. All parameters are passed as WORD values. (ex: ~myArray(2,5)~ ) 3. Added TCPWasReset ( see page 462)() API to allow the application layer to be notified if an underlying socket reset has occurred (ex: remote node disconnects, cable is disconnected and times out, user calls TCPDisconnect ( see page 446)(), etc.). The reset state is latching, which allows the application layer to detect if a remote node disconnects and a new connection occurs on the same socket before the application can detect the original disconnection through the TCPIsConnected ( see page 453)() API. 29
3
Microchip TCP/IP Stack Help 4. Added a counter to the UDPPerformanceTest module and made it supress transmission if an Ethernet link is not present. 5. Added TCPIP WebVend App example application to the main stack distribution. This corresponds to three new Microchip Webinars being published on the HTTP2 server usage topic. Fixes: 1. Fixed MPFS2.exe PC utility from crashing if you attempt to generate an MPFS classic .bin/.c/.s output file. 2. Fixed RCONbits definition for HPC_EXPLORER hardware profile when using the HI TECH PICC-18 compiler. 3. Fixed a MPFSGetFilename ( see page 274)() bug when using C30 and MPFS2 images stored in program memory. Thanks to Billy Walton on the Microchip Ethernet forum for identifying this issue. 4. Fixed a TCP RX FIFO corruption problem which would occur if the remote node sent more data than could fit in our RX FIFO in a single packet. The GeneticTCPClient.c module was subject to experiencing this problem when connected to www.google.com's servers. 5. Fixed a DHCP client UDP socket leak if you called DHCPDisable() after the DHCP client had already obtained a UDP socket. Thanks go to Matthew Kendall on the Microchip Ethernet forum for identifying this problem. 6. Fixed a SNMP Server module bug testing a string length (with respect to SNMP_COMMUNITY_MAX_LEN ( see page 328)) being off by one, resulting in possible memory corruption. Thanks go to Matthew Kendall on the Microchip Ethernet forum for identifying this problem. 7. Cleaned up some C30 compiler warnings related to macro definitions with inadequate parenthesis in them. 8. Fixed HTTP2 module sometimes returning a 501 error instead of a correct web page when being bombarded with new connection requests. 9. Fixed a TickGet ( see page 516)*() API problem where the returned tick value could be off by 64K ticks occasionally on PIC24 and dsPIC processors. 10.Fixed SMTP client module failing to send email when attempting to send an email with a `CC' or `BCC' field that was in ROM while the `To' field was in RAM or visa versa. 11.Fixed TCP module sending an incorrect sequence number in RST packets sent when in the TCP_SYN_SENT state and an invalid segment arrives. In prior stack versions, some TCP client applications might take a very long time to recover in the event of a power failure, reset, and subsequent reconnect to a remote server that still thinks the old connection is still active. With this fix, reconnections should be possible almost immediately after a power failure because the correct RST packet will cause the old connection to get closed right away. 12.Fixed a TCP socket leak problem that would occur over if the local PIC called TCPDisconnect ( see page 446)() and the remote node didn't send us a correct FIN response. Sockets ( see page 149) could previously get lost in the TCP_FIN_WAIT_2 state and wouldn't recover unless the application called TCPDisconnect ( see page 446)() a second time with the same socket handle. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. TFTPc module has not been tested with this version. 3. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 4. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail. 5. HI-TECH PICC-18 projects will not correctly set the processor configuration fuses through code using the __CONFIG() macro. Ensure that the configuration fuses are manually set correctly via the MPLAB IDE Configuration Bits dialog. This problem has been observed with compiler version 9.50PL3. 6. MAC.h RXSIZE precompiler test for proper range doesn't work. This is not a functional problem, just a compile-time configuration test. Ensure that you don't over allocate MAX_TCP_SOCKETS, TCP_TX_FIFO_SIZE, TCP_RX_FIFO_SIZE, or MAX_HTTP_CONNECTIONS. 7. GenericTCPClient ( see page 95) example of downloading a web page from www.google.com is extremely slow. The default TCP socket has too little RX space to accept ( see page 166) a full packet sent from Google's servers, so the remote server must retransmit a lot of data, slowing the transfer down a lot. Making TCP_RX_FIFO_SIZE 536 bytes or 30
3
Microchip TCP/IP Stack Help bigger and correspondingly shrinking MAX_TCP_SOCKETS will correct this problem.
****** v4.11 27 August 2007 ****** IMPORTANT NOTE: You must use MPLAB 7.62 or higher to successfully open the MPLAB projects. Changes: 1. Added a Microchip TCP/IP Stack Users' Guide to document the stack features/modules/and APIs and address the stale AN833 documentation. Note that this is a work in progress. Many modules have yet to be documented in the Users' Guide. 2. Added HTTP2 module. This HTTP module includes a whole new API and supreme new features, such as POST support, cookies support, browser authentication support, and more. 3. Added MPFS2 module. This module is required for the new HTTP2 module and performs better while having fewer limitations. Long filenames and folders are now supported. 4. Added a new GUI based MPFS2.exe PC utility. The older MPFSv2.exe GUI application and MPFS.exe command line tool has been retired. The new utility has advanced features, such as MPFS2 file format support, GZIP compress, etc. 5. Added a TFTP bootloader. This is a stand alone project and currently only supports the PIC18F97J60 family of PIC processors with internal Ethernet. 6. Added UART2TCPBridge.c file and STACK_USE_UART2TCP_BRIDGE option to TCPIPConfig.h. This new module acts as a TCP and UART bridge, with a high priority UART interrupt and dedicated UART TX and RX FIFOs for minimum UART latency and maximum performance. By default, the bridge acts as a TCP server and listens on port 9761. The UART baud rate defaults to 19200. The bridge can be reconfigured to act as a TCP client. 7. Added Simple Network Time Protocol (SNTP) client. This module automatically obtains the current time (date) from the Internet. Enable this module by defining STACK_USE_SNTP_CLIENT in TCPIPConfig.h. Obtain the current time (in seconds since 00:00:00 1970) by calling the SNTPGetUTCSeconds ( see page 371)() API. 8. Added support functions Base64Encode ( see page 211)() and Base64Decode ( see page 211)() in Helpers.c. Base 64 is required for the new HTTP2 module, but of general use to many applications. 9. Added SMTP Authentication ( see page 86) support to the SMTP Client. To use this, set the SMTPClient.Username and SMTPClient.Password string pointers to a non-NULL value before calling SMTPSendMail ( see page 306)(). Applications implementing email transmission capabilities should expose these options to the end-user for configuration. To use SMTP servers that do not support the AUTH LOGIN authentication command, simply leave the SMTPClient.Username and SMTPClient.Password pointers as their default NULL value. 10.Converted DHCPDisable() from a macro to a real function and added the complementary DHCPEnable() function. These two functions can be used at run time to dynamically switch between using a static IP address and configuration and DHCP assigned IP address and configuration. 11.Updated StringToIPAddress ( see page 221)() to work more robustly, including the ability to decode host name strings and determine if they contain a valid IP address or not. Also, the complementary ROMStringToIPAddress ( see page 221)() function was added. 12.Updated the DNS module. Now, if you give it an IP address string to resolve, it will convert the string to an IP address and immediately return without querying the DNS. 13.Shrunk the advertised TCP Maximum Segment Size from 576 bytes to 528 bytes. This might improve compatibility if your TCP data has to propagate over nodes with small MTUs and you have a correspondingly large TCP RX FIFO defined. 14.Performed some maintenance on the FTP.c file. No significant functionality has been changed, but some potential problems were corrected. 15.Altered Tick.c file and API. Now, the Tick module can operate maximum precision, returning the value of the actual Timer as it is counting, without disturbing the timer count by writing to it or disabling it. Three new APIs were added, TickGetDiv256 ( see page 516)(), TickGetDiv64K ( see page 517)(), and TickConvertToMilliseconds ( see page 515)(). Internally the tick counter is now 48-bits wide and as accurate as your Timer clock source, allowing you to use it as a Real Time Clock. 16.Added PIC24FJ64GA004_PIM hardware profile. This hardware profile is intended for use with the PIC24FJ64GA004 PIM on the Explorer 16 development board. In this mode, BUTTON2 and BUTTON3 and several of the LEDs do not work correctly due to lack of I/O pins on this device. Also, you cannot have the POT and TEMP jumpers on the PIM bridged because these signals are multiplexed with the SDO1/SDI1 pins needed for the Ethernet PICtail Plus. 31
3
Microchip TCP/IP Stack Help 17.Removed most ROM APIs when using a 16-bit compiler (C30). PIC24s and dsPICs usually don't need separate ROM functions since the Program Space Visibility feature maps ROM into RAM space. All ROM APIs are still supported, but they are now macros to base RAM APIs. This change saves a couple of kilobytes of code space on PIC24 and dsPICs. 18.Improved MyTCB structure caching. This should reduce TCP packet processing overhead with the ENC28J60 where TCBs are stored in the Ethernet RAM. 19.MAX_RETRY_COUNTS TCP configuration option has been renamed to TCP_MAX_RETRIES ( see page 480). 20.FTP server is no longer enabled by default. HTTP2 now supports POST, so you can upload new webpages through the /mpfsupload page now. FTP required two precious TCP sockets. 21.Began adding hooks for an SSL/TLS transport for secure HTTPS and other future stack modules. Note that these cryptographic modules are not available at this time. Configuration options such as MAX_SSL_CONNECTIONS do nothing and should not be modified. 22.Username has changed for all of the modules. Now all modules have a default username of "admin" and password of "microchip". Previously, the FTP and Telnet ( see page 485) modules used "ftp" and "telnet" respectively for the usernames. Fixes: 1. Fixed a SendFile() bug in HTTP.c where parsing dynamic cgi files could send garbage back to the web browser sometimes. Thanks go to Matt Watkins on the Microchip Ethernet forum for identifying this issue. 2. Fixed an off by one error in the calculation of RESERVED_TCP_MEMORY. Previously, the last TCP socket's RX FIFO would incorrectly overlap with the Ethernet RX buffer, causing incoming packets to occasionally be corrupted or the incoming data on the last socket to get corrupted. 3. Fixed the QWORD_VAL's dword struct element types. dword.LD and dword.HD were incorrectly defined as WORDs instead of DWORDs. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for identifying this issue. 4. Fixed the incorrect processing of received IP fragments with a non-zero offset. This stack does not support IP packet reconstruction due to the limited amount of available RAM. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for noticing this behavior. 5. Board now only responds to ping requests to our IP address, the directed subnet broadcast address, or the broadcast address of 255.255.255.255. Previously, it would respond to any ping request to any IP address, assuming the MAC address was correct. 6. Fixed a memory corruption/UDP packet loss problem when handling incoming UDP packets. Previously, StackTask() would incorrectly continue processing more packets if it came upon a UDP packet. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for identifying this issue. 7. Fixed the SMTPClient.ROMPointers.Server flag having an inverted meaning. Previously, the SMTP client module would treat the SMTPClient.Server pointer as a ROM pointer if this bit was cleared. In most cases, this would cause the SMTP client to return an error code of 0x8000 when the SMTPClient.SMTPServer ( see page 311) address pointer was set. 8. Fixed the DHCP Server module from incorrectly parsing received packets which had a DHCP_PARAM_REQUEST_IP_ADDRESS option followed by more options. Previously due to the length miscalculation, the parser would enter a random state, depending on the packet's contents. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for identifying this issue. 9. Fixed potential incorrect results when UDPIsGetReady ( see page 527)() was called and a previous application did not call UDPDiscard ( see page 525)() on an RX packet. Now, StackTsk() calls UDPDiscard ( see page 525)() as appropriate to let it know when it's old RX data is being thrown away. This fixes a potential bug in the DHCP Server module and makes the UDP API more robust. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for identifying the potential DHCP server issue. 10.Fixed a potential ARP bug where the Gateway's MAC address would be returned for an IP address on the local subnet. This unusual case would occur when two application tasks were using the ARP module at the same time and the second application was trying to resolve an IP address off of our subnet. Thanks go to Iñaki Esparza on the Microchip Ethernet forum for pointing this issue out. 11.Fixed an PIC18F97J60 family MAC layer bug where MACGetArray() might not correctly increment the Ethernet read pointer if a NULL pointer was given for the destination. The C compiler might have optimized the function so that it would increment the read pointer one less than it was supposed to. 12.The TCP module now acknowledges TCP Keep-Alive packets which will help prevent connection loss if the remote node fills up our RX FIFO and then our window-update packet gets lost on the network/Internet. In stack version 4.02, a zero-window probe would have been required to restore the communications. 13.Fixed a TCP RX FIFO corruption issue that would occur in (uncommon) circumstances when too many out-of-order segments arrived such that a second "hole" would have been required to accommodate the data. Thanks go to Iñaki Esparza and his eagle eyes on the Microchip Ethernet forum for finding this corner case bug. 14.Inline assembly in the ETH97J60.c file has been modified to accommodate the C18 Extended mode and C18 Auto default storage class. Previously, the Ethernet module would transmit garbage packets when using the C18 32
3
Microchip TCP/IP Stack Help parameter stack. 15.Fixed potential buffer overflow in NBNS.c's NBNSGetName ( see page 288)() function where an unexpected string length retrieved from the packet could cause random memory corruption. 16.Fixed some potential PIC18F97J60 family Ethernet module transmit lockup conditions that occur on some networks. Previously blocking while() loops would wait indefinitely for the ECON1bit to become clear by hardware, which the hardware might never have done. 17.In MainDemo.c, a call to DelayMs() was being made using a value of 100ms. This was too long for the underlying Delay1KTCYx() C18 function and would result in a shorter than expected delay when compiled with C18. This has been fixed with a loop. Thanks go to Andy123 on the Microchip Ethernet forum for pointing this problem out. 18.Fixed a potential C18 memory overlaying problem in the TickUpdate ( see page 518)() function. Previously, the local variable used in this function might have been overlayed on other memory, resulting in random memory corruption as the ISR occurred. 19.The demo AJAX web pages in the TCPIP Demo AppWebPages folder now correctly display and self-refresh in Firefox 2. Previously, it would work in Firefox 1.5 and Microsoft Internet Explorer, but not Firefox 2. Thanks go to "gohsthb" on the Microchip Ethernet forum for identifying this correction. 20.Rewrote the GenericTCPServer.c example to not use an application RAM FIFO for buffering. Since the TCP module implements its own FIFOing, the application has limited need for its own FIFO too. This fixes a previous bug where the GenericTCPServer ( see page 98) was not checking the number of incoming bytes with the remaining size available of the App FIFO. This would have previously resulted in a buffer overflow, corrupting the RX data if too much arrived all at once. 21.Fixed a potential MPFS classic inline ASM30 assembly code problem where web pages stored in internal Flash and C30 with optimizations enabled could result in data corruption. 22.Fixed a UDPPut ( see page 528)() tracking problem that would result in extra bytes being appended to the end of a packet if the UDPSetTxBuffer ( see page 531)() function was used. This previously caused the SNMP module to send some junk data at the end of its packets. 23.Fixed a potential TCP problem where transmitted FIN packets might not get retransmitted properly if the remote node never acknowledged the data that was transmitted just before the FIN was sent. 24.Fixed a NetBIOS Name Service bug where the response packet would sometimes get sent to an incorrect address. It now consistently responds to the unicast MAC/IP address of the NBNS query packet. 25.Added padding to all transmitted DHCP messages to make the minimum UDP payload at least 300 bytes. This fixes compatibility with some older BOOTP relay devices which discard smaller packets. Thanks go to Dave Collier on the Microchip Ethernet forum for pointing this problem out. 26.Substantially shrunk the number of retransmission attempts made in the TCP_SYN_RECEIVED state. This improves recovery time when attacked by a SYN flood Denial of Service event. The recovery time is now 7 seconds (3 total packets) instead of 31 seconds (6 total packets) 27.Fixed the possibility of the NetBIOS Name Service module giving out the board's static IP address before a DHCP lease could be obtained. NBNS requests are now only serviced when originating from nodes on the same subnet. 28.Fixed storage of MPFS classic in internal program memory when using the HI-TECH PICC-18 compiler. 29.Substantially revised TCP.c, fixing many TCP bugs and possibly adding new ones. Thanks go to Michael Rubinstein for finding several of these TCP problems. 30.The DNS client module will now time out and return failure if the DNS server cannot be ARPed or does not respond to the DNS query. Each timeout is set to 1 second and 3 total ARP and 3 total DNS query attempts are possible. Previously, it would retry indefinitely, causing the calling application to deadlock. Known Problems: 1. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 2. TFTPc module has not been tested with this version. 3. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to reenable it's DHCP server. 4. HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail. 5. HI-TECH PICC-18 projects will not correctly set the processor configuration fuses through code using the __CONFIG() macro. Ensure that the configuration fuses are manually set correctly via the MPLAB IDE Configuration Bits dialog. This problem has been observed with compiler version 9.50PL3. Testing and Performance Notes: 1. Make sure to use MPLAB IDE 7.62 or higher with this version. Versions below 7.61 will not work. Version 7.62 has cool new features like C auto-word complete and function parameter tooltips that can be enabled (disabled by default). 33
3
Microchip TCP/IP Stack Help 2. Testing was done using MPLAB C18 version 3.12, MPLAB C30 version 3.01, and HI-TECH PICC-18 version 9.50PL3. Make sure to upgrade your tools to at least these versions.
****** v4.02 10 April 2007 ****** IMPORTANT NOTE: You must use MPLAB 7.41 or higher to successfully open the MPLAB projects. IMPORTANT NOTE2:If an external serial EEPROM memory is used to store AppConfig, it's contents will be invalidated the first time you run this version, restoring the AppConfig defaults. The AppConfig structure has been optimized. IMPORTANT NOTE3:If an external serial EEPROM memory for MPFS, you will need to recreate the MPFS image and program your EEPROM. A 32 bit addressing format is now used. Changes: 1. Implemented TCP RX packet order correction logic. The stack can now accept ( see page 166) TCP frames that arrive out-of-order without requiring the remote node to go through a retransmit cycle. This dramatically improves RX performance when communicating over the Internet. 2. UDPOpen ( see page 524)() now can handle a NULL pointer for remoteNode. In this case, the broadcast IP/MAC addresses will be used for the remoteNode (destination address of outbound packets). 3. Recreated MPLAB projects for the HI-TECH PICC-18 compiler. These were temporarily absent from 4.00RC. This project works with the PIC18F97J60 with internal Ethernet module, assuming the correct compiler version is present. 4. Moved all the headers around. Most of them are in "Microchip SolutionsMicrochipIncludeTCPIP Stack" now. This change was made to again be more compatible with other (future) Microchip software libraries. 5. New UDPPut ( see page 528)() behavior. Now, if space in the Ethernet TX buffer runs out, the packet will not automatically be transmitted. You must call UDPFlush ( see page 526)() to cause the packet to be transmitted. 6. Added UDPGetArray ( see page 527)(), UDPPutArray ( see page 529)(), UDPPutROMArray ( see page 529)(), UDPPutString ( see page 530)() and UDPPutROMString ( see page 530)() user API functions. These functions perform substantially better than calling UDPPut ( see page 528)() successively and allow greater application programming flexibility. 7. Changed TCPPutString ( see page 460)() and TCPPutROMString ( see page 459)() APIs to now return an updated string pointer instead of a count of bytes successfully placed in the TX buffer. 8. Added UDPPerformanceTest.c. By default this module causes UDP packets containing 1024 bytes of application data to be broadcasted on UDP port 12345. Use a packet sniffer, such as Wireshark (http://www.wireshark.com/) to capture and derive stack overhead/UDP TX performance characteristics with this module. Note that this test uses the UDPPutROMArray ( see page 529)() function. Applications which use successive calls to UDPPut ( see page 528)() will be slower. To enable this module, #define STACK_USE_UDP_PERFORMANCE_TEST in TCPIPConfig.h. 9. Added TCPPerformanceTest.c. By default this module listens on TCP port 12345. When a remote client connects, this server module will being transmitting the maximum possible amount of application data that it can, given your TCP TX FIFO size. Use a packet sniffer, such as Wireshark (http://www.wireshark.com/) to capture and derive stack overhead/TCP TX performance characteristics with this module. Any TCP client can be used, including readily available utilities such as the telnet.exe utility available on Microsoft Windows XP. To use it to connect ( see page 168) to the test module, run: "telnet.exe xxx.xxx.xxx.xxx 12345" where xxx.xxx.xxx.xxx is the board's IP address. Note that this test uses the TCPPutROMArray ( see page 459)() function. Applications which use successive calls to TCPPut ( see page 458)() will be slower. To enable this module, #define STACK_USE_TCP_PERFORMANCE_TEST in TCPIPConfig.h. 10.Added Reboot.c module. By default, this module listens on UDP port 30304. If the application byte 0x00 arrives on this port, the PIC will reset. This is primarily useful for remote Bootloader entry. #define STACK_USE_REBOOT_SERVER in TCPIPConfig.h to enable this module. Note that since no encrypted challenge/response algorithm is currently implemented, this module is a Denial of Service vulnerability, so it should not be enabled unless there is a specific need for it. 11.Made the TickUpdate ( see page 518)() ISR routine execute in the low priority ISR instead of the default high priority ISR. The Microchip TCP/IP stack does not need 34
3
Microchip TCP/IP Stack Help any interrupts except this low priority timer. 12.Renamed STACK_USE_DHCP macro to STACK_USE_DHCP_CLIENT 13.Added STACK_USE_MPFS macro. 14.Changed UDPIsPutReady ( see page 528)() to return a WORD instead of a BOOL. The WORD is the number of bytes that can be put into the buffer. 15.Changed MACGetArray() to accept ( see page 166) a NULL pointer. If NULL, the retrieved data will simply be discarded. This also changes the behavior of UDPGetArray ( see page 527)() and TCPGetArray ( see page 451)() to match, throwing bytes away if a NULL pointer is given. 16.Added a very simple DHCP Server module. This module has limitations and is useful for a single client only. Its purpose is to allow you to directly connect ( see page 168) the board to a standard PC through a crossover cable (no other network nodes attached). The server is coded to automatically disable itself if the DHCP client is also enabled and another DHCP server is detected on the network. This allows both the DHCP server and DHCP client to coexist without any manual reconfiguration. 17.Added DNSResolveROM ( see page 183)() function for resolving host names that are stored in program memory, ex: literal strings. 18.Added a TCP automatic transmit/window update timer. It defaults to TCP_AUTO_TRANSMIT_TIMEOUT_VAL ( see page 478) (40ms) after the first get or put operation following the last automatic transmit/window update. This timer enhances performance, especially when streaming data over the Internet where round trip times can be several tens to low hundreds of milliseconds. This also improves application coding flexibility as TCPFlush ( see page 450)() need not be called anymore. 19.Added TCP delayed ACKnowledgement timer. This conserves bandwidth by transmitting fewer ACKs and prevents inadvertently influencing remote slow start/collision avoidance and fast retransmit algorithms. 20.Completely rewrote ICMP (ping) server module. It is now much smaller (ROM and RAM), faster, and can handle packets of 576 bytes or larger, if no IP fragmentation occurs. 21.Rewrote StackTsk() stack manager. It is much simpler now. 22.Added TCPFind ( see page 447)(), TCPFindArray ( see page 447)(), and TCPFindROMArray ( see page 449)() user API functions. These functions peek inside a given TCP socket's RX FIFO (without removing anything) and looks for a particular byte or array of bytes. This should greatly simplify the creation of application code whenever variable length fields are used (ex: text strings terminated by rn). It supports case insensitive text searching or binary searching, as well as an offset to start searching at. 23.Added TCPGetRxFIFOFree ( see page 452)() user API. It returns the number of bytes of free space in the TCP's RX FIFO. 24.Changed default TICK resolution to 1ms (from 10ms) and improved accuracy. 25.Added outbound ping capabilities (i.e. board can now ping another board or a PC). To enable these features, define STACK_USE_ICMP_CLIENT. This will enable several new APIs, including ICMPBeginUsage ( see page 261)(), ICMPSendPing ( see page 262)(), ICMPGetReply ( see page 263)(), and ICMPEndUsage ( see page 264)(). The functions should be called in this order. See the PingDemo ( see page 99)() function in MainDemo.c for an example of how to use them. By default, pushing BUTTON3 (left-most one) will cause a ping to be sent to 4.78.194.159 (ww1.microchip.com). The response time will be displayed on the LCD (assuming your development board has an LCD). 26.Cleaned up C30 3.00 signed/unsigned warnings. 27.Removed PIC18F97J60_TEST_BOARD hardware profile support. This stack no longer supports it due to the old beta silicon (with errata) mounted on these boards. 28.Added support for ROM pointers for all of the SMTP strings (To, From, CC, Subject, etc.). If you use a ROM string, you must also set the corresponding SMTPClient.ROMPointers.xxx bit to let the SMTP module know which type of pointer was provided. See the SMTPDemo ( see page 94)() code in MainDemo.c for and example calling sequence using both ROM and RAM strings for the various fields. Fixes: 1. Fixed a critical TCP buffer corruption issue where the start of a TCB header overlapped with the last byte of the RX FIFO from the previous socket. This bug affected version 4.00RC only. 2. ETH97J60.c, TCPIP.h, and TCPIP Stack Version.txt were correctly readded to the TCPIP Demo App-C18 project using relative paths instead of absolute paths. 3. UDPOpen ( see page 524)() now dynamically assigns a local port number if you call it and give it a 0x0000 port number. This should fix some UDP applications from not working (ex: DNS Client module) with some computers/routers/networks which throw away traffic originating from the invalid port 0x0000 value. 4. Fixed a ENC28J60 bank selection error that would occur if an application called GetCLKOUT() in ENC28J60. By default, this function is not called. 5. UnencodeURL (
see page 225)() function in Helpers.c is now tested and working.
6. Fixed a TCP Window Update problem when TCPGetArray ( performance could have been terrible on reception.
see page 451)() was used. Before the problem was fixed,
7. Fixed a unintended TCP connection close if the socket was idle for about a minute. Now, TCP sockets will remain open indefinitely if there is no traffic going on. 8. Serial numbers >32K are now displayed correctly on the serial port as a positive value when C18 is used and the board is placed in configuration mode (BUTTON0 is depressed on power up). 35
3
Microchip TCP/IP Stack Help 9. HI-TECH PICC-18 compiler would previously incorrectly initialize the AppConfig structure. 10.Previously a processor reset was possible when accessing items in the AppConfig strucutre on 16 bit MCUs (PIC24, dsPIC) due to unaligned word accesses. This was fixed by reordering the Flags byte in the APP_CONFIG structure. 11.Rewrote DHCP client state machine, fixing the previously known problem where it would not perform a new discovery if it was trying to renew a lease with an offline DHCP server. 12.Fixed a critical deadlock problem in the ETH97J60.c MAC layer driver for the PIC18F97J60 family Ethernet controller. Previously, it was possible (although rare) that the DMAST or TXRTS bits would get stuck set if too much Ethernet traffic was received within a short interval. Previously, the MACFlush() function was unnecessarily setting TXRST, which it should not do while the Ethernet interface or DMA is being used. 13.Fixed an HTTP server state machine problem where a new connection occurring too soon on a previously used socket could cause the HTTP server to no longer respond. 14.Fixed a potential memory corruption error in the HTTPGetVar() callback which would exceed the bounds of the VarString array when returning the VAR_STACK_DATE variable. 15.Fixed a TCP transmission sequence tracking problem whenever data is retransmitted and new unflushed data is also in the TX FIFO. Thanks go to Matt Watkins on the Microchip Ethernet forum for identifying this issue. Known Problems: 1. RTL8019AS MAC layer driver has not been updated for new TCP module. Users requiring RTL8019AS support should continue to use stack version 3.75. 2. I2CEEPROM.c has not been tested or completed. Continue to use I2CEEPROM.c from stack version 3.75 if this file is needed. 3. Telnet ( see page 485) server module does not implement a lot of Telnet ( see page 485) functions. As a result, it will likely not display correctly or work at all with some Telnet ( see page 485) clients. The server was tested with the Microsoft telnet.exe utility which is provided with Microsoft Windows. 4. TFTPc module has not been tested with this version. 5. The default demo web pages which use AJAX do not automatically refresh themselves when viewed in Firefox 2.0.0.1. Earlier Firefox versions (1.5ish) probably work without any problem. 6. Files may be inaccessible in your MPFS if compiled with C18 for internal flash program memory and your total MPFS content is large (around 64KB or larger). The code attempts to access the ROM memory using a near rom pointer when a far rom pointer is needed. 7. If using MPLAB 7.52 all .s files that are compiled with C30 will not have the corresponding object file get stored in the correct directory. As a result, if you are compiling with C30 and with MPFS_USE_EEPROM not defined (i.e. storing web pages in internal program memory), the project won't link (throws a undefined reference to `MPFS_Start'). As a workaround, remove the Intermediates Directory in the MPLAB project. Alternatively upgrade MPLAB to a newer version. MPLAB IDE 7.60+ may have this fixed. 8. If the DHCP client and DHCP server are used at the same time and you connect ( see page 168) two similar boards to each other (ex: two PICDEM.net 2 boards connected via a crossover cable), a race condition can occur where both nodes will disable their DHCP server and neither board will get a successful DHCP lease. If this unlikely scenario occurs, as a work around, simply reset one of the boards to renable it's DHCP server. 9. HI-TECH PICC-18 projects may not compile when MPFS_USE_EEPROM is not defined and you are trying to store web page data in internal FLASH program memory. 10.HI-TECH PICC-18 projects may not compile when targeting the external ENC28J60 chip on the PICDEM.net 2 development board (instead of the internal Ethernet controller). This problem only applies when a PIC18F97J60 family part is the target. I.e. it compiles correctly for the HPC_EXPLORER + Ethernet PICtail. Testing and Performance Notes: 1. This stack version was compiled and tested with the following tool versions: -MPLAB IDE 7.52 -Microchip C30 version 3.00 -Microchip C18 version 3.10 -HI-TECH PICC-18 version 9.50PL3 2. Using the UDPPerformanceTest.c module, the stack can transmit around 220KBytes/second (1.75Mbits/second) of UDP application data on the PIC18F97J60 with internal Ethernet @ 41.66667MHz core clock, compiled using C18 3.10 with debug optimization settings. 3. Using the UDPPerformanceTest.c module, the stack can transmit around 392KBytes/second (3.14Mbits/second) of UDP application data on the PIC24HJ256GP610 with external ENC28J60 @ 40 MIPS, compiled using C30 3.00 with debug optimization settings. 4. Using the TCPPerformanceTest.c module, the stack can transmit around 58KBytes/second (464Kbits/second) of TCP application data on the PIC18F97J60 with internal Ethernet @ 41.66667MHz core clock, compiled using C18 3.10 with debug optimization settings, over Ethernet when using a tiny 200 byte TX TCP FIFO. Note that performance can be 36
3
Microchip TCP/IP Stack Help improved significantly by increasing the FIFO size and performance will drop significantly if the round trip TCP acknowledgement time is increased (ex: testing over the Internet instead of Ethernet). 5. Using the TCPPerformanceTest.c module, the stack can transmit around 69KBytes/second (558Kbits/second) of TCP application data on the PIC24HJ256GP610 with external ENC28J60 @ 40 MIPS, compiled using C30 3.00 with debug optimization settings, over Ethernet when using a tiny 200 byte TX TCP FIFO. Note that performance can be improved significantly by increasing the FIFO size and performance will drop significantly if the round trip TCP acknowledgement time is increased (ex: testing over the Internet instead of Ethernet). 6. Using the TCPPerformanceTest.c module, the stack can transmit around 178KBytes/second (1.42Mbits/second) of TCP application data on the PIC24HJ256GP610 with external ENC28J60 @ 40 MIPS, compiled using C30 3.00 with debug optimization settings, over Ethernet when using a larger 2000 byte TX TCP FIFO. Note that performance will drop significantly if the round trip TCP acknowledgement time is increased (ex: testing over the Internet instead of Ethernet).
****** v4.00RC 28 December 2006 ****** IMPORTANT NOTE: If an external serial EEPROM memory is used to store AppConfig, it's contents will be invalidated the first time you run this version, restoring the AppConfig defaults. The AppConfig structure has been optimized. IMPORTANT NOTE2: If an external serial EEPROM memory for MPFS, you will need to recreate the MPFS image and program your EEPROM. A 32 bit addressing format is now used. Changes: 1. Added Simple Mail Transfer Protocol (SMTP) client module and updated MainDemo.c to exercise the Email transmission functionality when a user pushes BUTTON0. 2. Added beta Telnet (
see page 485) server module. See Known Problems section.
3. Completely revamped the TCP module. A real transmit FIFO and receive FIFO are allocated for each TCP socket now. This greatly enhances RFC compliance, communications robustness, and makes application development easier. New APIs were added for putting and getting arrays and strings (including ROM variants). Several TCP related bugs are now fixed as a result. Please report any bugs found in the new implementation. 4. Added TCPPutArray (
see page 458)() API.
5. Added TCPPutROMArray ( 6. Added TCPPutString (
see page 460)() API.
7. Added TCPPutROMString ( 8. Added TCPGetArray (
see page 459)() API.
see page 459)() API.
see page 451)() API.
9. Changed TCPIsPutReady ( see page 454)() API. Instead of returning a BOOL, it now returns a WORD. The WORD is a count of the number of bytes that TCPPut ( see page 458)(), TCPPutArray ( see page 458)(), etc. can immediately place in the output buffer. MAKE SURE THAT YOUR CODE DOES NOT COMPARE THE RETURN RESULT OF TCPIsPutReady ( see page 454)() DIRECTLY TO TRUE. For example, "if(TCPIsPutReady ( see page 454)(MySocket ( see page 309)) == TRUE){...}" must be converted over to: "if(TCPIsPutReady ( see page 454)(MySocket ( see page 309))){...}". 10.Changed TCPIsGetReady ( see page 454)() API. Instead of returning a BOOL, it now returns a WORD. The WORD is a count of the number of bytes that TCPGet ( see page 450)() or TCPGetArray ( see page 451)() can immediately obtain. MAKE SURE THAT YOUR CODE DOES NOT COMPARE THE RETURN RESULT OF TCPIsGetReady ( see page 454)() DIRECTLY TO TRUE. For example, "if(TCPIsGetReady ( see page 454)(MySocket ( see page 309)) == TRUE){...}" must be converted over to: "if(TCPIsGetReady ( see page 454)(MySocket ( see page 309))){...}". 11.Changed TCPDiscard ( see page 446)() return type from BOOL to void. 12.Removed TCP_NO_WAIT_FOR_ACK option. It was defaulted to disabled in the last two releases of the stack and is not needed with the new TCP module. 13.Updated DNS module to include two new required APIs: DNSBeginUsage ( see page 182)() and DNSEndUsage ( see page 182)(). These functions control a one bit ownership semaphore to allow multiple applications to use the DNS module in series. If invoked correctly, this will prevent unintended bugs resulting from two applications trying to use the DNS module at the same time. Old applications, such as those based around the GenericTCPClient.c example must be updated to use these functions. 14.Started using a new project structure and folders. You must use MPLAB 7.41 or higher (stack is tested on MPLAB 7.50)
37
3
Microchip TCP/IP Stack Help to use the default workspaces/projects, which include files using relative paths. This should improve compatibility with some future code libraries released by Microchip. StackTsk.h was broken into TCPIPConfig.h, HardwareProfile.h, and StackTsk.h. TCPIPConfig.h now includes all stack configuration options and HardwareProfile.h contains all hardware options. No macros need be globally defined in MPLAB project now. TCPIP.h is the only header applications must include now, for any/all modules used. 15.Combined ARP.c/ARP.h and ARPTsk.c/ARPTsk.h into a single file pair: ARP.c/ARP.h. Applications built using a prior stack revision must remove all instances including "ARPTsk.h" and replace it with "ARP.h" instead. The ARP module is now simpler, more linear (easier to read), and being in one source file, allows the C compiler to optimize better. 16.Added PIC18F67J60_TEST_BOARD hardware profile to HardwareProfiles.h. This hardware profile is designed for 05-60091 (Rev 1), a development board that is not in production at this time. 17.Added DSPICDEMNET1 and DSPICDEMNET2 hardware profiles to HardwareProfiles.h for eventual support of the Microchip dsPICDEM.net 1 and dsPICDEM.net 2 demo boards. These two boards use the RTL8019AS Ethernet controller and a 24LC515 EEPROM. These changes are currently incomplete and these profiles cannot be used. 18.Began rewriting I2CEEPROM.c to support 16 bit CPUs, including the dsPIC30F6014 used on the dsPICDEM.net 1 and 2 demo boards. Note that work here is incomplete and cannot be used as a result -- see Known Problems section. 19.Partially updated RTL8019AS.c to support 16 bit CPUs, including the dsPIC30F6014 used on the dsPICDEM.net 1 and 2 demo board. Note that work here is incomplete and cannot be used as a result -- see Known Problems section. 20.Updated SNMP.c to use new typedefs in GenericTypedefs.h. Also SNMP was tested in this version. SNMP.mib was updated some to better reflect current hardware. 21.Added AN870 SNMP callbacks to MainDemo.c (a feature that was missing in 3.xx releases). This code will get compiled when STACK_USE_SNMP_SERVER is defined in TCPIPConfig.h. 22.Removed all instances of MPFS_USE_PGRM for storing in internal FLASH program memory. Storage in internal program memory is now the default. Define MPFS_USE_EEPROM to override the default and store MPFS in an external EEPROM memory. 23.Decreased program memory needed for Announce.c module by about 180 bytes. Multiple inline calls to UDPPut ( see page 528)() were removed. 24.UDP checksum checking logic has been improved. The UDP layer now avoids writing the pseudo header checksum in the RX buffer. 25.Swapped endianess of the returned checksum from CalcIPBufferChecksum ( see page 213)(). Rewrote CalcIPBufferChecksum ( see page 213)() in Helpers.c. This improves consistency. 26.Improved swapl() in Helpers.c. 27.Improved USART baud rate (SPBRG) calculation for PIC18s. Rounding is now done to chose the most optimal value and the code will automatically select high baud rate mode (BRGH=1) if possible. Additional improvements can be made if using a newer PIC18 with the 16 bit baud rate generator. 28.Added GenericTCPServer.c example file to complement GenericTCPClient.c. The server is enabled by defining STACK_USE_GENERIC_TCP_SERVER_EXAMPLE in TCPIPConfig.h. 29.Renamed STACK_USE_GENERIC_TCP_EXAMPLE definition to STACK_USE_GENERIC_TCP_CLIENT_EXAMPLE for consistency with new server example. 30.Defaulted MPFS.exe to generate binary MPFS images using 32 bit addressing. MPFS.h has been modified to also default to use 32 bit addressing of external EEPROM images. You must rebuild any old MPFS images and reprogram them if upgrading from a previous TCP/IP stack revision, which defaulted to use 16 bit addressing. 31.Updated MPFS.exe to #include "TCPIP.h" instead of "..HeadersCompiler.h" in C files generated by the utility. 32.Added MPFSv2.exe PC utility for generating large MPFS images in program memory (ASM30 code) for C30 users. Previously, the C30 compiler placed a limit of less than 32KB of total MPFS size due to the PSV window size limitation on PIC24/dsPIC devices. To get around the limitation, use the new MPFSv2.exe utility to generate an .s file which can be included in your project instead of the .c file generated by the traditional MPFS.exe utility. Fixes: 1. Fixed a bug in ARPProcess ( see page 159)() which would incorrectly send an ARP response to an incorrect MAC & IP address if a TX buffer wasn't immediately available. 2. Fixed a TCP bug where TCPIsGetReady ( see page 454)() would return TRUE even if no data was left in the recieved packet. Previously you had to call TCPGet ( see page 450)() one last time and have it fail before TCPIsGetReady ( see page 454)() would return FALSE. 3. Modified TCP state machine. Established connections will no longer automatically close if left idle for approximately 45 seconds. Note that your application needs to ensure that no sockets unintentionally get lost (For example: a server socket that received data only is established and the cable breaks while connected. In this case, the socket would never be detected as being disconnected since the server never attempts to transmit anything). 4. Stopped overclocking dsPIC33 and PIC24H devices. Previously PLLFBD was incorrectly set to 39 instead of 38 to yield a resulting Fosc of 84MHz (42MIPS) instead of 80MHz (40MIPS) with the default Explorer 16 development board. Thanks go to Matt Watkins on the Microchip Ethernet Forum for pointing this error out. 5. Corrected a bug in IP.c where IPHeaderLen would not be properly initialized if a NON_MCHP_MAC was used (ex: RTL8019AS) and IPSetRxBuffer() was called. This bug did not affect ENC28J60 or PIC18F97J60 family support. Thanks 38
3
Microchip TCP/IP Stack Help go to Darren Rook for identifying this issue. 6. Updated checksum checking code in ENC28J60.c for latest silicon DMA checksum errata. 7. Declared TickCount in Tick.c/Tick.h as volatile and implemented an interrupt safe reading procedure in TickGet ( see page 516)(). Since this multibyte variable is modified in the ISR and read in the mainline code, these changes are needed to prevent rare inconsistency bugs. 8. Fixed Announce.c so the unicast remoteNode of the requesting packet would be used rather than the remoteNode of the last received packet, which may not be correct when transmitting. Thanks go to Brett Caulton for identifying this issue. 9. Fixed a DHCP bug which would cause DHCP renewals to continually occur after only 60 seconds once the original lease expired. Thanks go to Brett Caulton for identifying this issue and fix. 10.Fixed a potential TCP socket leak in the FTP module. Previously FTPDataSocket would not be reliably initialized nor closed if the connection was killed forcefully (user killed application, cable disconnected while transferring, etc.). Known Problems: 1. RTL8019AS MAC layer driver has not been updated for new TCP module. Users requiring RTL8019AS support should continue to use stack version 3.75. 2. I2CEEPROM.c has not been tested or completed. Continue to use I2CEEPROM.c from stack version 3.75 if this file is needed. 3. Telnet ( see page 485) server module is still in development. No user authentication features are currently implemented. Some telnet clients may render the telnet server output incorrectly (in the wrong locations or wrong colors). Testing has only been done with the Microsoft Windows telnet.exe utility that comes Windows XP. 4. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease is offline. The board will continue to use the expired IP address until the DHCP server comes back online, at which point the lease will be renewed or a new discovery will occur. A new discovery should occur after timing out, instead. It is believed that this problem has always existed in previous stack revisions. 5. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease does not include Option 54, the Server Identifier. A new discovery should occur after timing out. It is believed that this problem has always existed in previous stack revisions. 6. TFTPc module has not been tested with this version. 7. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up).
****** v3.75 14 August 2006 ****** Changes: 1. Added beta DNS client module (DNS.c). DHCP was also updated to obtain a DNS server address. Added AppConfig.PrimaryDNSServer IP address. Added STACK_USE_DNS configuration macro. To use the DNS client, call DNSResolve ( see page 183)() with the server name, ex: DNSResolve ( see page 183)("www.microchip.com"), and then periodically call DNSIsResolved ( see page 184)() until it returns TRUE, ex: DNSIsResolved ( see page 184)(&IPAddressDestination). Only one DNS resolution can be in progress at a time. Because the DNS client is a beta module, the API or code may change before being finalized. No formal DNS API documentation is available yet. 2. Added beta NetBIOS Name Service responder module (NBNS.c). Added AppConfig.NetBIOSName string. Added STACK_USE_NBNS configuration macro. Added MY_DEFAULT_HOST_NAME macro in StackTsk.h. Now, whenever a NetBIOS broadcast attempting to resolve AppConfig.NetBIOSName arrives, a response will be made. This form of name resolution only works on a single subnet. Off the subnet, manual registration in a DNS server or other means will be needed to allow the local Host Name to be recognized and translated to an IP address. The default NetBIOS name for the board is "MCHPBOARD". To test the NetBIOS Name Service module, try entering http://MCHPBOARD/ into your web browser instead of the board's IP address. 3. Added beta HTTP client module (GenericTCPClient.c). This module demonstrates how to make a TCP client application. To test this module, uncomment the STACK_USE_GENERIC_TCP_EXAMPLE macro in StackTsk.h, recompile, and then press the BUTTON1 button while the stack is running. RemoteURL ( see page 96)[] should be downloaded from 39
3
Microchip TCP/IP Stack Help ServerName ( see page 96)[] and written to the UART. For the default values of ServerName ( see page 96)[] and RemoteURL ( see page 96)[], the HTML search page for "Microchip" will be fetched from "www.google.com" and written to the serial port. No formal documentation is available for this example yet. 4. Added Embedded Ethernet Device Discoverer PC project to aid in embedded product discovery when connected to a network and demonstrate how to write PC applications which can communicate with embedded devices. The source code for this device is included. It can be built using the Microsoft Visual C# 2005 Express Edition compiler. At the time of stack release, this 3rd party PC development tool can be downloaded at no cost from http://msdn.microsoft.com/vstudio/express/. If using only the Microchip Device Discoverer executable file without the Visual C# compiler, the .NET Framework 2.0 must be installed on the local PC. The application setup utility should allow dynamic downloading of this component if the target machine does not already have it installed. 5. Updated Announce.c to listen ( see page 172) and respond to discovery requests sent to UDP port 30303 starting with the character 'D'. To test this functionality, use the Embedded Ethernet Device Discoverer on a PC connected to the same subnet. 6. Updated UART configuration menu to accommodate the new beta module configuration options (DNS server address, device host name). 7. Increased MPFS reserve block to 64 bytes from 32. Also, because the APP_CONFIG structure was updated, all current MPFS images and data stored in deployed EEPROMs needs to be updated. 8. Added a means to erase (invalidate) the onboard EEPROM using the BUTTON0 momentary switch (right-most switch on demo boards with multiple switches). To erase the EEPROM, hold down BUTTON0, RESET the board (press and release MCLR switch), and then continue to hold down BUTTON0 for an additional 4 seconds. If you press MCLR again, the EEPROM contents will now be invalid. If you press '0' on the UART, the same configuration that was read prior to invalidating the contents will be written back into the EEPROM. Invalidating the EEPROM allows the MY_DEFAULT_* constants to get loaded into a previously programmed EEPROM chip. Because of change #7, this procedure should be done for all currently programmed EEPROMs to prevent anomalous values from being read. 9. remoteNode in StackTsk.c was changed from private to global scope. Now external modules can reference the address of the last received packet. Announce.c uses this to send a unicast response to a broadcast discovery request. 10.All stack modules that can be disabled (DHCP.c, FTP.c, etc) now will no longer emit a compiler error if you have it in the project without defining the appropriate macro (STACK_USE_DHCP, STACK_USE_FTP, etc). It will simply generate no machine code when compiled and the stack will not use that module. Make sure the proper macro is defined for each module that you wish to use. 11.Added SetRXHashTableEntry() to ENC28J60.c. This function can be used to set the appropriate bit in the Hash Table registers to join a particular multicast group. 12.Added Realtek RTL8019AS Ethernet controller support to the stack. MAC.c was renamed to RTL8019AS.c. This Ethernet controller is not recommended for new designs. RTL8019AS support was reintroduced to provide ongoing assistance to former Application designs implementing this chip. For new applications, use the Microchip ENC28J60 or PIC18F97J60 family of microcontrollers. 13.Added I2C EEPROM support for MPFS storage. In older 2.xx stack revisions, I2C EEPROM was supported by the XEEPROM.c file. This file has been renamed to I2CEEPROM.c. It is mutually exclusive with SPIEEPROM.c, and only one may be included in the project at a time. 14.Added new hardware definitions to Compiler.h. Pin mappings for the PICDEMNET and PIC18F97J60_TEST_BOARD boards have been added. FS_USB was also defined; however, it is untested and not recommended. See Compiler.h. The PIC18F97J60_TEST_BOARD is a non-production board that some Early Adopters of the PIC18F97J60 family parts have. 15.Changed type definitions for BYTE_VAL, WORD_VAL, DWORD_VAL, and moved the generic typedefs to GenericTypeDefs.h from StackTsk.h. This should improve compatibility with some future code libraries released by Microchip. 16.LCDBlocking.c module was modified to support 4-bit interfaces to LCD modules. The PICDEM.net board has the module wired using a 4-bit bus. Fixes: 1. Fixed a serious MAC TXBuffer leak in TCP.c. Previously TCP.c would allocate a buffer for each socket in use, but under heavy traffic conditions (ex: user holds down F5 on web browser), the buffer handle might have been discarded before releasing the buffer. As a result all TCP connections would have lost the ability to send any application data after the TXBuffer pool ran out. 2. In the TCP_SYN_SENT TCP state, ACKs may only be received (as opposed to SYN+ACK packets) if the remote node thinks the connection is already open. A RST is now sent in response to an unexpected ACK, which may improve reconnection time when this (rare) condition occurs. 3. A bug was present in the UDP module where remote MAC addresses would be cached for each socket, even when UDPInit ( see page 534)() or UDPClose ( see page 525)() was called, or the microcontroller was reset. As a result, responses to incoming packets could have been sent to the wrong MAC address. UDP Sockets ( see page 149) are now properly initialized/closed.
40
3
Microchip TCP/IP Stack Help 4. Fixed a potential timing bug in LCDBlocking.c. For lower values of CLOCK_FREQ, insufficient delay time was given to the LCD module, potentially causing improper operation. 5. Changed PIC24F to default to the XT oscillator fuse rather than HS. The PIC24FJ128GA010 data sheet, rev. C reports that 8MHz should be used with XT mode, not HS mode like prior data sheets. 6. Added a couple of wait states to the Realtek RTL8019AS MAC layer module for NICPut() and NICGet(). Previously, the PICmicro could not operate above approximately 25MHz without losing communication with the RTL8019AS chip. 7. Updated PC based MPFS utility. When generating C files to be added to your MPLAB project, the include path to "Compiler.h" is now "..IncludeCompiler.h". The output file, ex: "MPFSImg.c" should be placed in the "Source" subfolder before compiling. For example, if you are in the main stack folder with the MPLAB projects, type: "mpfs /c WebPages SourceMPFSImg.c" 8. IP Gleaning will now get properly disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled. The stack will still respond to ping requests which have the wrong destination IP address, but a correct MAC address. However, the stack will continue to keep its statically defined IP address when DHCP/IP Gleaning are disabled and the ping arrives. 9. SPIEEPROM.c now saves and reconfigures the EEPROM_SPICON1 register (SSPCON1) before reading or writing to the SPI. After the read/write, it restores the saved state. This allows the SPI bus to operate at different speeds, depending on what peripheral is being accessed if other devices share the bus and can support different speeds. In particular, this fixes the SPI @ 10.4MHz problem on the PICDEM.net 2 board when using the ENC28J60. Known Problems: 1. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease is offline. The board will continue to use the expired IP address until the DHCP server comes back online, at which point the lease will be renewed or a new discovery will occur. A new discovery should occur after timing out, instead. It is believed that this problem has always existed in previous stack revisions. 2. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease does not include Option 54, the Server Identifier. A new discovery should occur after timing out. It is believed that this problem has always existed in previous stack revisions. 3. When an MPFS .c image file is added to a C30 project, a linking error reporting insufficient contiguous .const memory may occur when too much data is in the MPFS image (PSV window size limitation). Using the PSV window, 1 out of every 3 program memory bytes is wasted. 4. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work. 5. SNMP, TFTPc modules have not been tested with this version. 6. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up). 7. The C30 linker may misplace the __CONFIG2 section or disallow usage of MPFS images that are too big (add too much to the .const code section). The consequences of this are that the first configuration word at 0x157FC may not get set through code (must use the Configuration Bits dialog instead), and/or the project will not compile. This problem has been observed with C30 ver. 2.02 on the PIC24FJ128GA010 product. To work around this problem, the p24FJ128GA010.gld linker script has been modified. Specifically, line 68 has been commented out, which causes the linker to place all .text sections after placing all absolute sections. SSR 25966 in the C30 2.02 release notes may be related. 8. It is observed with the Realtek RTL8019AS Ethernet controller and the demo AJAX web page which self refreshes rapidly, that occasional HTTP GET requests sent by the computer do not get received by the HTTP server. This is believed to be a RTL8019AS MAC layer bug. The TCP protocol handles the packet loss, but application performance suffers while waiting for the TCP retransmission. This problem is not observed with ENC28J60.c or ETH97J60.c MAC layers. 9. The HI-TECH compiler version 9.50PL1 crashes when compiling LCDBlocking.c with 4 bit mode (PICDEMNET) and using a warning level of -3 or higher. To work around the problem, the HI TECH projects were set to use warning level -4. Guiding Notes: 1. To use the stack on a classic PICDEM.net demo board with the Realtek Ethernet controller, a PIC18F452 processor, and Microchip C18: -Use the C18EEPROM MPLAB project -Change the processor in the MPLAB IDE -Change linker script to "18f452i.lkr" in the MPLAB project. Use the one provided in the Linker subfolder, it has been modified to make more RAM available. -Update the hardware definitions macro. Click on Project -> Build Options... -> Project -> MPLAB C18 -> Add PICDEMNET, remove HPC_EXPLORER) -Remove ENC28J60.c from the project -Remove SPIEEPROM.c from the project -Add RTL8019AS.c to the project -Add I2CEEPROM.c to the project -Enable all compiler optimizations (Project -> Build Options... -> Project -> MPLAB C18 -> Categories Optimization -> Enable all)
41
3
Microchip TCP/IP Stack Help
****** v3.60 12 July 2006 ****** General Information: This stack version is being publicly released, so the following changes are with respect to the prior public stack release (v3.02). Interim stack changes for version 3.16 and 3.50 are documented below for those using non-public releases, but can be ignored by most people. Troubleshooting notes: 1. If you have an Ethernet PICtail revision 2.1 and are having reliability issues when viewing the fast-refresh demo web page, you may need to install resistors in series with the ENC28J60 SI, nCS, and SCK pins. The recommended value is 100 to 200 ohms. This will reduce signal undershoot caused by long traces (parasitic inductance), which can violate the absolute maximum electrical specs and cause SPI data corruption. The HPC Explorer Rev 5 has fairly long traces to the PICtail connector. 2. Enabling C30 2.02 compiler optimizations on the dsPIC33FJ256GP710, PIC24HJ256GP610 ES chips may produce unreliable code. 3. When changing a C30 project to a PIC24H or dsPIC33F processor on the Explorer 16 demo board, the JTAG configuration fuse should be disabled to free the I/O pins associated with it. JTAG is enabled by default. 4. This stack release was tested using MPLAB 7.40, C18 version 3.03, C30 version 2.02, and HI TECH PICC18 version 9.50PL1. 5. When using the Ethernet PICtail board and HPC Explorer demo boards, make sure to plug the power into the Ethernet PICtail and not the HPC Explorer. The HPC Explorer's power regulator cannot provide enough current. Changes: 1. Source files have been split into separate directories. To compile old applications with this new stack, application source files may need to be updated to include the proper path to the stack header files. 2. New MPLAB projects have been created: -C18EEPROM: Equivalent to the previously named "mpnicee" project. Designed for PIC18's using the C18 compiler. Web page content, board's IP address, MAC address, DHCP enabled state, etc. is stored in an external SPI EEPROM (25LC256 on demo boards). FTP Server demo is included. -C30EEPROM: New supporting PIC24 and dsPIC controllers using the C30 compiler. Similar to C18EEPROM. -C18ProgramMem: Equivalent to the previously named "mpnicpg" project. Web page content stored in internal FLASH program memory. Board's IP address, MAC address, DHCP enabled state, etc. is stored only in RAM and defaults are loaded from MY_DEFAULT_* constants in StackTsk.h. FTP Server demo is not included. Web pages cannot be updated remotely. -C30ProgramMem: New supporting PIC24 and dsPIC controllers using the C30 compiler. Similar to C18ProgramMem. -HTC18EEPROM: Equivalent to the previously named "htnicee" project. Designed for PIC18's using the HI TECH PICC18 compiler. Similar to C18EEPROM. -HTC18ProgramMem: Equivalent to the previously named "htnicpg" project. Designed for PIC18's using the HI TECH PICC18 compiler. Similar to C18ProgramMem. 3. Created hardware definitions (pins, interrupt flags, special registers, etc) in Compiler.h for easy changing of hardware. Four demo board combinations are supported out-of-box now: -EXPLORER_16: Explorer 16 motherboard + Ethernet PICtail Plus daughter card. Tested with dsPIC33FJ256GP710, PIC24HJ256GP610, and PIC24F128GA010 ES PIMs. -HPC_EXPLORER: PICDEM HPC Explorer motherboard + Ethernet PICtail daughter card. Tested with PIC18F8722 onboard and PIC18F87J10 PIM. -DSPICDEM11: dsPICDEM 1.1 motherboard + Ethernet PICtail daughter card (manually air wired). See Compiler.h for proper pins to air wire. Tested with dsPIC30F6014A PIM. -PICDEMNET2: PICDEM.net 2 motherboard (PIC18F97J60) Change boards by changing the defined macro (Project -> Build Options... -> Project -> MPLAB Cxx -> Add macro). When moving to custom hardware, add an appropriate profile to Compiler.h. YOUR_BOARD is present as a placeholder. 4. Added Ethernet PICtail Plus schematic (reference ENC28J60 daughter card design for Explorer 16 demo board). These boards have a Microchip part number of AC164123. 5. Latest ENC28J60 rev. B5 errata workarounds added. The code checks the EREVID register and implements the appropriate workarounds as needed for the silicon revision, so rev. B1, B4, and B5 are all supported in this stack release. 6. Significantly revised demonstration web page content in WebPages folder to use AJAX technology. Using asynchronous JavaScript code executing in the web browser, the status sections of the page are updated rapidly from the web server without doing a full page refresh. As a result, a virtually real time update of the potentiometer and button values can be displayed. Due to the constant use of new TCP sockets, multiple simultaneous users are not recommended. See the Index.cgi file for a simple static method of retrieving dynamic variables from the HTTP server. 42
3
Microchip TCP/IP Stack Help 7. Changed IP Gleaning procedure. Now, if DHCP is enabled, the DHCP module will continue to look for a new IP address/renew existing IP address if the IP address is configured using IP Gleaning. Previously, the DHCP module would be disabled once a successful ICMP packet was received and used to configure the IP address. 8. MAX_RETRY_COUNTS is 3 (previously it was 3, but an interim release changed it to 5). 9. Updated TCP state machine. It now includes the TCP_FIN_WAIT_2 state. Some other changes were made to handle errors more robustly. 10.AN0String and AN1String now return all characters excluding the null terminator when the HTTP server calls HTTPGetVar (except when the string is 0 length). Previously, the null terminator was returned as well. 11.Dynamic pages (ie: .cgi files) are now served with an expired HTTP header to prevent browser caching and allow more dynamic content to be displayed. 12.Support for the HI TECH PICC18 compiler has changed. Special Function Register bits and other definitions have changed substantially from the previous HI TECH PICC18 projects in TCP/IP stack version 3.02 and earlier. The C18/C30 SFR and SFRbits naming conventions are now used and special remapping macros in Compiler.h are used to maintain a consistent syntax. The HI TECH PICC18 projects were tested with compiler version 9.50PL1 on the HPC Explorer board (PIC18F8722). 13.FTP client hash printing has been added to the FTP server. Now, whenever a chunk of data is successfully uploaded to the device, a '#' character will appear on the FTP client screen. The numbers of bytes each '#' represents is variable. 14.To improve maintainability, built in support for the "Compatible" A/D converter present on older PIC18 parts (ex: PIC18F452) has been removed. 15.Removed old LCD code originally provided for the PICDEM.net demo board. 16.Added LCDBlocking.c and LCDBlocking.h, which implement simple routines for writing to the LCD module on the Explorer 16 and PICDEM.net 2 development boards. The LCD on the dsPICDEM 1.1 board is not supported. The stack version and IP address are shown on the LCD on power up. 17.UART functions in MainDemo.c were replaced with C18 and C30 peripheral library functions. However, because the UART peripheral libraries are not being updated for newer silicon devices, the code was copied into UART.c and is compiled with the stack. 18.Multiple TX buffer support has been implemented. Most stack layers have been touched. ENC28J60.c has the most extensive changes. Each socket may use only one TX buffer. 19.Implemented TCP retransmission support regardless of if TCP_NO_WAIT_FOR_ACK is defined or not. 20.TCP_NO_WAIT_FOR_ACK in StackTsk.h has been undefined by default. This should increase default TCP connection robustness. Packets sent from the stack to the remote node will now be detected and retransmitted if lost or corrupted. 21.All TCP packets are now retransmitted immediately after being initially transmitted when TCP_NO_WAIT_FOR_ACK is undefined. This improves throughput greatly when communicating with systems which wait a long time before transmitting ACKs. TCP/IP stacks, such as that used by Microsoft Windows, implement the TCP Delayed Acknowledgement algorithm, which is why this retransmission is necessary for high performance. The double transmission feature can be disabled in the Microchip TCP/IP stack by defining "DEBUG" either in the TCP.c file or the project compiler macros section. Using DEBUG mode can be useful when trying to look for errors using Ethreal [ http://www.ethereal/ ]. 22.Lowered TCP_START_TIMEOUT_VAL ( see page 483) from 60 seconds to 3 seconds. 60 seconds is an unreasonably long timeout for modern day network speeds. 23.Native support for the SLIP module has been dropped.
Fixes: 1. A new IP address obtained via IP Gleaning will now update the LCD (if present), invoke the Announce ( module (for MCHPDetect.exe), and output the new address out the RS232 port.
see page 152)
2. DHCP client will now correctly use the first DHCP offer received when connected to a network running multiple DHCP servers. Previously, the board would get no IP address when attached to a network with multiple DHCP servers (unless the DHCP request was transmitted before a second DHCP offer was received -- a relatively rare event). Additionally, DHCPLeaseTime does not get reset to 60 seconds or the value stored in the last DHCP packet received prior to receiving the ACK. 3. UDPProces() will now correctly process received UDP packets that have a 0x0000 checksum field. The UDP protocol specifies that 0x0000 means the checksum is disabled. Packets with a 0x0000 checksum were previously thrown away unless the calculated checksum also happened to be 0x0000. 4. The TCPIsPutReady ( see page 454)() function will now honor the remote node's TCP window size. In other words, if the remote application pauses or cannot handle the incoming data rate, the TCP flow control feature will correctly function. Previously, if the remote node ran out of incoming buffer memory, the TCP layer would still allow more data to be transmitted. This would result in the loss or corruption of application data, with a potentially broken connection. The change requires 2 more bytes of RAM per TCP socket (TCB array). Known Problems: 1. On PICDEM.net 2 board ENC28J60 and 25LC256 EEPROM share the same SPI1 module. At 3.3V, the 25LC256 is only 43
3
Microchip TCP/IP Stack Help rated to 5MHz SPI clock, but the code is setting it to 10.4MHz because the MACInit() function reconfigures the same SPI1 module. 2. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease is offline. The board will continue to use the expired IP address until the DHCP server comes back online, at which point the lease will be renewed or a new discovery will occur. A new discovery should occur after timing out, instead. It is believe that this problem has always existed in previous stack revisions. 3. DHCP will continually send out DHCP Request packets when the lease expires and the original DHCP server that gave the lease does not include Option 54, the Server Identifier. A new discovery should occur after timing out. It is believe that this problem has always existed in previous stack revisions. 4. The MPFS utility has not been updated. When creating a .c image file, the include path for the Compiler.h file will be incorrect and need to be manually updated to "..IncludeCompiler.h". 5. When an MPFS .c image file is added to a C30 project, a linking error reporting insufficient contiguous .const memory may occur when too much data is in the MPFS image (PSV window size limitation). Using the PSV window, 1 out of every 3 program memory bytes is wasted. 6. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work. 7. SNMP, TFTPc modules have not been tested with this version. 8. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up). 9. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled. 10.The C30 linker may misplace the __CONFIG2 section or disallow usage of MPFS images that are too big (add too much to the .const code section). The consequences of this are that the first configuration word at 0x157FC may not get set through code (must use the Configuration Bits dialog instead), and/or the project will not compile. This problem has been observed with C30 ver. 2.02 on the PIC24FJ128GA010 product. To work around this problem, the p24FJ128GA010.gld linker script has been modified. Specifically, line 68 has been commented out, which causes the linker to place all .text sections after placing all absolute sections. SSR 25966 in the C30 2.02 release notes may be related. Guiding Notes: 1. To change processors using a C18* project: -Change the processor in the MPLAB IDE -Change linker script (ex: 18f87j10i.lkr) in the MPLAB project. Use *i.lkr if the ICD2 is going to be used to debug with. -Update the hardware definitions in Compiler.h or change your demo board selection macro. (Project -> Build Options... -> Project -> MPLAB Cxx -> PICDEMNET2, etc) 2. To change processors using a HTC18* project: -Change the processor in the MPLAB IDE -Update the hardware definitions in Compiler.h or change your demo board selection macro. (Project -> Build Options... -> Project -> MPLAB Cxx -> PICDEMNET2, etc) 3. To change processors using a C30* project: -Change the processor in the MPLAB IDE -Change linker script (ex: p33FJ256GP710.gld) in the MPLAB project. -Update the hardware definitions in Compiler.h or change your demo board selection macro. (Project -> Build Options... -> Project -> MPLAB Cxx -> DSPICDEM11, etc) -Disable JTAG configuration fuse, if enabled 4. When using the PICDEM.net 2 board, to write code targeting the PIC18F97J60 family Ethernet module: -Remove ENC28J60.c from the project -Add ETH97J60.c to the project -Plug the Ethernet cable into the left-most RJ45 jack (next to LCD) 5. When using the PICDEM.net 2 board, to write code targeting the ENC28J60 Ethernet device: -Make sure ENC28J60.c is in the project -Make sure that ETH97J60.c is not in the project -Plug the Ethernet cable into the right-most RJ45 jack (next to board edge) 6. When using the PICDEM.net 2 board, to write code targeting an Ethernet PICtail module (ENC28J60): -Make sure ENC28J60.c is in the project -Make sure that ETH97J60.c is not in the project -Make sure that the Ethernet PICtail J9 jumper is in the 2-3 position (default). -Properly update the hardware profile in Compiler.h. ENC_CS_TRIS and ENC_CS_IO need to be changed from D3 to B3. -Plug the Ethernet cable into the PICtail -Plug power into the PICDEM.net 2 board 7. When using the Explorer 16 and Ethernet PICtail Plus demo boards, make sure to mate the PICtail to the motherboard using the topmost socket position, leaving the cable hanging over prototyping area. If SPI2 is desired, the PICtail should have the same orientation but be installed in the middle slot. Using SPI2, the hardware profile will need to be updated in Compiler.h.
44
3
Microchip TCP/IP Stack Help
****** v3.50 13 April 2006 ****** Changes: 1. Improved dsPIC33F and PIC24H support. UART functions are included now instead of precompiled object files for the PIC24F. The 12-bit A/D converter is now shown in use on the demo web content. When changing a C30 project to a PIC24H or dsPIC33F processor on the Explorer 16 demo board, the JTAG configuration fuse should be disabled to free the I/O pins associated with it. JTAG is enabled by default. 2. Added LCDBlocking.c and LCDBlocking.h, which implement simple routines for writing to the LCD module on the Explorer 16 development board. The stack version and IP address are shown on the LCD on power up. 3. Added "C18ProgramMem" and "C30ProgramMem" MPLAB projects for MPFS storage (web page content) on on-chip program memory. These projects are equivalent to the previously named "mpnicpg" project in prior stack releases. 4. Multiple TX buffer support has been implemented. Most stack layers have been touched. ENC28J60.c has the most extensive changes. Each socket may use only one TX buffer. 5. Implemented TCP retransmission support when TCP_NO_WAIT_FOR_ACK is undefined. 6. TCP_NO_WAIT_FOR_ACK in StackTsk.h has been undefined by default. This should increase default TCP connection robustness. 7. All TCP packets are now retransmitted immediately after being initially transmitted when TCP_NO_WAIT_FOR_ACK is undefined. This improves throughput greatly when communicating with systems which wait a long time before transmitting ACKs. 8. Lowered TCP_START_TIMEOUT_VAL (
see page 483) from 60 seconds to 3 seconds.
9. Increased MAX_RETRY_COUNTS from 3 to 5 times. 10. The example HTTP server now returns a content expiration date which has already past. This prevents web browser caching and allows more dynamic content to be displayed. 11. Added WebPages_JScript folder, with new web pages that support dynamic page updates without a full page reload. A tiny page of dynamic variables is returned by the web server and Javascript executing on the target web browser changes DOM elements as needed. Button S5 (RA7) on the Explorer 16 demo board and S1 (RB0) on the HPC Explorer demo board changes the page color scheme. The rapid dynamic updates do not work on some web browsers (Internet Explorer works, Firefox does not). Known Problems: 1. MPFS utility has not been updated. When creating a .c image file, the include path for the compiler.h file will be incorrect and need to be manually updated. 2. When an MPFS .c image file is added to a C30 project, a linking error reporting insufficient contiguous .const memory may occur (PSV window size limitation). 3. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work. 4. SNMP, TFTPc, SLIP modules have not been tested with this version. 5. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up). 6. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled. 7. The IP address being outputted out the RS232 port and through the Announce ( happen when the IP address is configured using IP Gleaning.
see page 152) module does not
8. On the PIC24F with C30 compiler optimizations enabled (such as Option 3, maximum speed), the project may not work. The PIC24F headers that come with C30 ver. 2.01 declare several SFRs without using the volatile keyword. 9. dsPIC30 support is incomplete. Currently PIC18, PIC24F, PIC24H, and dsPIC33F processors are supported.
45
3
Microchip TCP/IP Stack Help
****** v3.16.00: 06 March 2006 ****** Changes: 1. Added unified support for both the Microchip C18 and C30 compilers. The intention is to allow one code base to be compiled for any PIC18, PIC24F/H, dsPIC30, or dsPIC33 product (with adequate memory). See the "Tested Using" section for what is known to work. 2. To improve maintainability, support for the HI-TECH PICC18 compiler has been dropped. 3. New project workspaces have been created, "C30EEPROM.mcw" and "C18EEPROM.mcw". C18EEPROM.mcw is equivalent to the previously named "mpnicee.mcw." C30EEPROM is intended to be used for PIC24 and dsPIC 16-bit controllers. 4. Source files have been split into separate directories. 5. Latest ENC28J60 rev. B5 errata workarounds added. The code checks the EREVID register and implements the appropriate workarounds as needed for the silicon revision, so rev. B1, B4, and B5 are all supported in this stack release. 6. Removed old LCD code originally provided for the PICDEM.net demo board. 7. To improve maintainability, built in support for the "Compatable" A/D converter present on older PIC18 parts (ex: PIC18F452) has been removed. 8. UART functions in MainDemo.c were replaced with C18 and C30 peripheral library functions. Tested Using: 1. Software: -MPLAB version 7.31.01 -C18 version 3.02 -C30 version 2.01 2. Hardware: -PICDEM HPC Explorer rev. 4 (PIC18F8722) + Ethernet PICtail Daughter Board (ENC28J60 B1) -Explorer 16 rev. 4 (PIC24FJ128GA010 ES and dsPIC33FJ256GP710 ES) + Ethernet PICtail+ Daughter card (ENC28J60 B1). 3. Notes: -MPLAB 7.31.01 is a development build. The publicly available version 7.31 should work fine, with the exception of being unable to program dsPIC33 and PIC24H parts with the ICD 2. -No dsPIC30 or PIC24H parts have been tested yet. Known Problems: 1. MPFS utility has not been updated. When creating a .c image file, the include path for the compiler.h file will be incorrect and need to be manually updated. 2. When an MPFS .c image file is added to a C30 project, a linking error reporting insufficient contiguous .const memory may occur. 3. On the PIC24FJ128GA010, it is observed that some inbound packets are lost from time to time with no anticipated reason. 4. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work. 5. SNMP, TFTPc, SLIP modules have not been tested with this version. 6. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up). 7. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled. 8. The IP address being outputted out the RS232 port and through the Announce ( happen when the IP address is configured using IP Gleaning.
see page 152) module does not
9. Multiple TX buffer support is not fully inplemented in the MAC layer, ENC28J60.c. Stack behavior when TCP_NO_WAIT_FOR_ACK is undefined may be unexpected.
****** v3.02.00: 20 Feb 2006 46
3
Microchip TCP/IP Stack Help
****** Fixes: 1. Changed TXSTART in ENC28J60.c to stop wasting a byte. 2. Changed RXSTOP in ENC28J60.c to always be an odd value to properly implement an ENC28J60 silicon errata workaround. 3. Changed initialization of ERXRDPT in MACInit() to agree with the current errata. Changes: 1. Licence agreement 2. Schematics and other board files to the Ethernet PICtail Daughter Board have been updated to revision 5. Of significant note, the nRESET pin has been freed and 200 ohm resistors were added to the ENC28J60 SI, nCS, and SCK pins. The added resistors reduce undershoot caused by stray trace inductance and strong host output drivers. Known Problems: 1. Testing on the PICDEM.net demo board with the Realtek RTL8019AS Ethernet controller has not been done. Moving to the HPC Explorer demo board has resulted in pinout and other hardware changes. 2. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work. 3. SNMP, TFTPc, LCD, SLIP modules have not been tested with this version. 4. The stack may behave incorrectly if compiled using the Hitech compiler with a high optimizations setting. 5. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up). 6. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled. 7. The IP address being outputted out the RS232 port and through the Announce ( happen when the IP address is configured using IP Gleaning.
see page 152) module does not
8. Multiple TX buffer support is not fully inplemented in the MAC layer, ENC28J60.c. Stack behavior when TCP_NO_WAIT_FOR_ACK is undefined may be unexpected.
****** v3.01.00: 18 Jan 2006 ****** Fixes: 1. Implemented latest ENC28J60 silicon errata workarounds. 2. Fixed a bug in TCP.c and UDP.c which would incorrectly write the packet checksum into the RX buffer incorrectly when the checksum field was exactly spanning the RX wrapparound boundary in the ENC28J60. This problem would have caused packets to be discarded in rare circumstances Known Problems: 1. Testing on the PICDEM.net demo board with the Realtek RTL8019AS Ethernet controller has not been done. Moving to the HPC Explorer demo board has resulted in pinout and other hardware changes. 2. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work. 3. SNMP, TFTPc, LCD, SLIP modules have not been tested with this version. 4. The stack may behave incorrectly if compiled using the Hitech compiler with a high optimizations setting. 5. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up). 6. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled. 7. The IP address being outputted out the RS232 port and through the Announce (
see page 152) module does not 47
3
Microchip TCP/IP Stack Help happen when the IP address is configured using IP Gleaning. 8. Multiple TX buffer support is not fully inplemented in the MAC layer, ENC28J60.c. Stack behavior when TCP_NO_WAIT_FOR_ACK is defined may be unexpected.
****** v3.00.00: 16 Jan 2006 ****** Changes: 1. The stack now targets the PICDEM HPC Explorer demo board (PIC18F8722 MCU) with an attached Ethernet PICtail Daughter Board (with the Microchip ENC28J60 Ethernet controller). 2. IP Gleaning is no longer enabled (STACK_USE_IP_GLEANING is not defined) by any of the default project files. 3. The IP address, whenever it changes, is outputted out the RS232 serial port in human readable form. Any terminal program, such as HyperTerminal can be used to read it. This allows the IP address to be easily determined when DHCP is used. The serial port defaults to 19200 baud when CLOCK_FREQ in Compiler.h is properly defined. Additions: 1. Microchip ENC28J60 Ethernet controller support. Support is included through the ENC28J60.c and ENC28J60.h files. Various other files were modified to take advantage of ENC28J60 specific features, like the hardware DMA/IP checksum engine. This new MAC driver incorporates several new functions which can be called from any layer above the MAC. The functions are: MACSetDuplex() MACPowerDown() MACPowerUp() MACSetPMFilter() MACDisablePMFilter() CalcIPBufferChecksum ( see page 213)() MACCalcRxChecksum() MACCalcTxChecksum() MACCopyRxToTx() See the ENC28J60.c file comments for function descriptions. The ENC28J60.c file also incroporates TestMemory() which can do a power on self test of various hardware functions. TestMemory() is included and used when MAC_POWER_ON_TEST is defined in StackTsk.h. It is undefined by default. Defining it will require some program memory. 2. Announce ( see page 152) module. Announce.c and announce.h have been added. When included in the project, STACK_USE_ANNOUNCE must be defined. This module will broadcast a UDP message to port 30303 containing the local MAC address whenever the local IP address changes. This addition is intended to facilitate device discovery on DHCP enabled networks and eliminate the need for an RS232 connection if board reconfiguration is not needed. To retrieve the UDP message on your computer, use the new MCHPDetect.exe program included in the MCHPDetect subfolder. 3. The spieeprom.c file was added to support SPI EEPROM chips for MPFS storage. ENC28J60.c and spieeprom.c may both be included and they will share the same SPI module. Improvements: 1. Renamed files/edited files so that the HI-TECH compiler won't raise messages stating that include files were spelled wrong. 2. Moved MAX_ICMP_DATA_LEN from StackTsk.c to ICMP.h file for easier maintenance. 3. Corrected STACK_USE_SIIP typo in dhcp.c file - Thanks to Gisle J.B. 4. Implemented UDP checksum logic in UDPProcess (
see page 534)() in UDP.c file.
5. Renamed CalcTCPChecksum() in tcp.c file to CalcIPBufferChecksum ( 6. Moved CalcIPBufferChecksum (
see page 213)().
see page 213)() to helpers.c to reuse it for UDP checksum calculation.
7. Modified UDPProcess ( see page 534)() in UDP.c and TCPProcess ( see page 468)() in TCP.c to include localIP as third new parameter. This makes pseudo header checksum calculation correct in both functions. StackTsk.h, UDP.h and TCP.h files were also modified to reflect these changes. 8. Modified TCP.C file to include compile-time check of STACK_USE_TCP define. If it is not defined, an error will be displayed. 9. Removed an unnecessary call to MACDiscardRx() when an IP packet is received but fails version, options length, or header checksum tests. 10. Changed LCD code to be compile time removable by undefining USE_LCD. Fixes: 1. IPHeaderLen in IP.c is initialized properly now when IPGetHeader() is called. 48
3
Microchip TCP/IP Stack Help 2. Under some circumstances, HandleTCPSeg ( see page 473)() would acknowlege, but throw valid received TCP packets away, resulting in loss of application data. An invalid comparison in HandleTCPSeg ( see page 473)() has been fixed to prevent this situation from occuring. *** Thanks go to Richard Shelquist for identifying this problem. 3. Fixed StackTsk.c file so that if a static IP address is used and the LINK is removed, the node IP address is not cleared. 4. Invalid ICMP echo replies are no longer generated for echo requests with a data length of 33 (one more than the configured maximum). 5. Changed MAX_OPTIONS_LEN from 20 to 40. The maximum IP options length is now in agreement with the IP RFC. 6. Changed IPSetRxBuffer() from a macro to a function. The function takes into account any options which may be present in the header of received IP packets. Previously, possible options were not taken into account when calculating the offset. Known Problems: 1. Testing on the PICDEM.net demo board with the Realtek RTL8019AS Ethernet controller has not been done. Moving to the HPC Explorer demo board has resulted in pinout and other hardware changes. 2. Sometimes when the FTP sever is used, an attempt to put a file is unsuccessful. The problem may be caused when an HTTP request to GET a file is made at the wrong time. 3. MACSetPMFilter(), MACDisablePMFilter(), and MACCopyRxToTx() have not been tested and possibly do not work. 4. SNMP, TFTPc, LCD, SLIP modules have not been tested with this version. 5. The stack may behave incorrectly if compiled using the Hitech compiler with a high optimizations setting. 6. Serial numbers >32K will be displayed on the serial port as a negative value when C18 is used and the board is placed in configuration mode (RB0 button is depressed on power up). 7. IP Gleaning may not get disabled when, through the RS232 configuration application, DHCP and IP Gleaning are disabled. 8. The IP address being outputted out the RS232 port and through the Announce ( happen when the IP address is configured using IP Gleaning.
see page 152) module does not
9. Multiple TX buffer support is not fully inplemented in the MAC layer, ENC28J60.c. Stack behavior when TCP_NO_WAIT_FOR_ACK is defined may be unexpected.
****** v2.20.04.01: 9/24/03 ****** 1. Recreated MPLAB projects to avoid problems when source is not at MCHPStack location.
****** v2.20.04: 9/5/03 ****** Fixes: 1. Modified DHCPReset() in DHCP.c to not reset DHCP state machine if it was previously disabled using DHCPDisable(). This would make sure that if DHCP module was enabled and application had run-time disabled DHCP and network cable is disconnected, stack will not clear its IP address.
2. Rebuilt mib2bib.exe file with static library options. This fixes problem where one tries to execute this exe, an error occurs about missing DLLs.
49
3
Microchip TCP/IP Stack Help
****** v2.20.03: ****** Improvements: 1. When DHCP is enabled, LINK is monitored and IP address is reset on disconnect. New IP configuration is obtained on LINK reconnect. - For RealTek only. Modified DHCP.c to add DHCPReset() Modified MAC.c to add MACIsLinked() Modified StackTsk.h to add BYTE_VAL def. Changes: 1. Modified SMSC91c111.c to add empty MACIsLinked() - will be populated in next rev. Bug Fixes: 1. Corrected DHCP logic to accept (
see page 166) first DHCP offer instead of second response.
2. Corrected DHCP logic to check for chaddr in DHCP offer and accept ( see page 166) one that matches with local MAC address. This will fix problem where if multiple nodes were on bus and all requested DHCP address, all would accept ( see page 166) response from one server instead of verifying who was intended node. 3. Fixed UDPClose ( see page 525)() in UDP.c to use INVALID_UDP_PORT ( see page 522) instead of INVALID_UDP_SOCKET ( see page 522) because of which a closed socket would not be scanned correctly. 4. Modified UDP.h to use long contsant designators for INVALID_UDP_OPRT to explicitly state that it is a long.
****** v2.20.02: ****** Beta version containing TFTP client module. Addition: 1. TFTP Client module - See TFTPc.* and TFTPcDemo.c for more information. See MpTFTPcDemo and HtTFTPcDemo projects for build information. Bug Fix: 1. UDPIsGetReady ( see page 527)() was modified to overcome compiler rule where only 8-bit value was used to evaluate non-zero condition. 2. ARPResolve (
see page 155)() in ARPTsk was fixed to clear Cache.IPAddr value.
****** v2.20.01: ****** Bug fix: 1. Fixed SMSC91C111.c where MACInit() would hand if ethernet link is not detected.
****** v2.20:
50
3
Microchip TCP/IP Stack Help
****** Bug Fixes: 1. General - Removed most of harmless warnings. 2. C18Cfg.asm - Fixed "include" instead of "define". 3. DHCP.c - Increased DHCP_TIMEOUT_VAL to 2 seconds. Fixed problem where UDP active socket was not set before calling UDP functions in SM_DHCP_BROADCAST state. 4. MAC.c - Fixed MACIsTxReady() where under heavy traffic it would always return FALSE. This fixes bug where all high level applications would stop transmitting. 5. TCP.c - Enabled portion of code that performs timeout logic even if TCP_NO_WAIT_ACK is defined. This fixes bug where occasionally, tcp applications such as HTTP server would stop working after few hours. 6. UDP.c - Fixed UDPGet ( see page 526)() where it would return FALSE on last good byte. Fixed UDPProcess ( page 534)() where it was calculating incorrect length.
see
Added bFirstRead flag with UDP sockets similar to TCP sockets so that whenever first UDP byte is read, MAC read pointer will be reset to begining of correct packet. This change fixes problem where if one transmits a packet while UDP packet is pending in a socket, next get to pending UDP socket would return wrong data. (This is apparent only when there is heavy network traffic) Known Issues: 1. HiTech v8.20 PL4 with all optimization enabled may not work properly. 2. C18 "Static" and "Auto" mode may not be used - there are too many local variables to fit in standard stack of 256 bytes. One may modify linker script file to avoid this limitation.
Improvements: 1. Modified TICK def. in Tick.h to unsigned long to support 32-bit wide SNMP tick. 2. Added SNMP Module (SNMP.c) 3. Added Two new demo projects - DemoSNMPApp and HtDemoSNMPApp. 4. Created MPLAB 6.X projects for different demo configurations. 5. MAC.c - Added MACGetTxOffset(). 6. MPFS.c - Added MPFSSeek (
see page 280)(), MPFSTell (
see page 285)().
7. MPFSImg.*- Rebuilt to reflect v2.20, footprint changes etc. 8. StackTsk.h- Enhanced WORD_VAL, DWORD_VAL defs. Added STACK_USE_SNMP and related compile-time checks. 9. UDP.h - Added UDPSetTx and UDPSetRx macros. Moved UDP_SOCKET_INFO ( file.
see page 538) structure to header
10. WebSrvr.c- Modifed MCHPStack version message and added DATE info to BoardSetup menu. 11. Added support for SMSC LAN91C111 10/100 Non-PCI ethernet controller Use "SMSC91C111.C" instead of MAC.c. "mpnicee_smsc" is a sample project that uses PIC18F8720 and SMSC NIC. "MasterDemo.c" is a main source file for above project that includes all modules - must use device with more than 32KB of memory.
****** v2.11:
51
3
Microchip TCP/IP Stack Help
****** Bug Fixes: 1. Fixed dhcp.c to make it work with new C18 startup code. Improvements: 1. Modified websrvr.c DownloadMPFS() to make use of compiler allocated XMODEM data block rather than use fixed address block starting at 0x400.
****** v2.10: 7/9/02 ****** Bug Fixes: 1. Fixed HTTP Server bug where a form submission with empty parameter value would not parse correctly.
****** v2.0: 5/22/02 ******
****** New Modules: ****** 1. Added UDP, DHCP, FTP and IP Gleaning 2. Added PICDEM.net LCD support 3. Added board setup through RS-232.
****** Improvements: ****** 1. Optimized serial EEPROM access routines in terms of speed and size (Replaced ee256.* files with eeprom*.h) 2. Improved board setup through RS-232.
****** Known Issues: ****** 1. LCD may not display properly on MCLR only. Workaround: 1. Debug XLCDInit() routine in "xlcdlh" 2. Always do POR reset.
52
3
Microchip TCP/IP Stack Help 2. SLIP connection is not very robust. Workaround: None at this time.
3. Hi-Tech Compiler: 1. Aggressive optimization breaks the functionality. Workaround: Apply optimization listed in each source file comment header. 2. In order to use V8.12, you will need to remove "FTP Server" from Ht*.pjt. You will also need to disable all optimizations.
4. C18 Compler: 1. Static model does not compile. Workaround: None at this time. 2. Overlay model breaks the functionality. Workaround: None at this time. 3. All modules does not fit in 32KB memory. Workaround: 1. None at this time. 2. Sample project disables some modules.
****** New Files: ****** ======================================================================================== ==================================== File Purpose ======================================================================================== ==================================== 1. delay.* Provides CLOCK_FREQ depenent delay routines. 2. dhcp.* DHCP client support 3. ftp.* FTP server 4. udp.* UDP socket support 5. xeeprom.* Improved ee256.* and renamed. 6. xlcd.* External LCD support. 7. version.log To track changes and history.
Microchip TCP/IP Stack Help None 2. Fixed "include" errors. None
3. compiler.h 1. Included "stdlib.h" in both C18 and Hi-Tech compilers. None 2. Moved CLOCK_FREQ from "stacktsk.h" to this file. None 3. Added PORTA defs. None
4. htnicee.pjt 1. Removed "ee256.c". None 2. Added "udp.c", "dhcp.c", "ftp.c", "xlcd.c", "xeeprom.c" files Add these files if needed.
7. http.c 1. Included compile-time verification that HTTP module is included. None 2. Put HTTP message strings into one array "HTTPMessages". None 3. Modified to return "Service Unavailable" message if MPFS is being None remotely programmed. 4. Modified SendFile() to make use of sequential EEPROM read. None
8. ip.c 1. Added one more paramter to IPGetHeader() to support IP Gleaning Custom apps using IP needs to be modified.
12. stacktsk.c 1. Replaced ee256.h with xeeprom.h None 2. Added IP Gleaning and DHCP support. None
13. stacktsk.h 1. Moved CLOCK_FREQ to compiler.h None 2. Added STACK_USE_DHCP, STACK_USE_FTP_SERVER etc. options None 3. Added compile-time enable/disable of modules based on selection of higher level modules. None 4. Modified MY_DEFAULT_MAC_BYTE? to use Microchip OUI id. None 5. Added compiler-time check to confirm available TCP sockets None 6. Added MSB and LSB macros. None 7. Added SerialNumber etc. to AppConfig structure None 8. Commented module selection defines: They are defined by cmopiler None command-line options. Real application should define them here in this file.
14. tcp.c 1. Moved TCP_STATE (
see page 466) and TCP_INFO to .h file.
None 55
3.2 Memory Usage
Microchip TCP/IP Stack Help
2. Fixed TCPIsConnected (
see page 453)()
None 3. Fixed TCPDisconnect (
see page 446)()
None 4. Modified TransmitTCP() to set receive window of one segment None 5. Modified TransmitTCP() to use max segment size equal to predefined value. None 6. Improved TCP State machine None
15. tick.c 1. Modified TICK type to 16-bit. None 2. Made use of TICK_PRESCALE_VALUE None 3. Added code to blink PICDEM.net "System LED" Remove if not required.
16. websrvr.c 1. Added LCD support N/A 2. Made TickUpdate (
see page 518)() on Timer0 interrupt
N/A 3. Added code to save/restore board configuration N/A 4. Added board setup via RS-232. N/A 5. Added call to FTP modules If needed, add this.
3.1 Stack Performance Note that this table will not appear in the PDF version of the help file; see the "TCPIP Stack Performance.htm" file in the TCPIP documentation folder in the Microchip Application Library help folder.
3.2 Memory Usage These tables contain the PIC program and data memory requirements for the TCP/IP stack. The first two rows list the program memory consumption of the stack's required files ( see page 134), and each additional row contains the additional 56
3.3 Peripheral Usage
Microchip TCP/IP Stack Help
memory required to implement specific modules. These values are approximations; the program memory size may increase depending on application code, or decrease based on optimizations of modules with overlapping code. Modules that require user-implemented API functions (SNMP, HTTP) are tested without additional code. The global data memory column includes only the RAM needed for the required structures in the stack; it does not include the memory used for socket allocation ( see page 149). The C18 code uses the PIC18F97J60 family Ethernet controller as the MAC/PHY chip; the C30 and C32 measurements are made using the ENC28J60 Ethernet controller (ENCX24J600 sizes are similar). All compilers include a separate Required Stack Code line for Wi-Fi applications using the MRF24WB0M as the network controller. These two Required Stack Code lines are mutually exclusive -- do not add them together. Instead, chose the line representing your network controller. These values are approximations obtained from TCP/IP Stack version 5.31. Note that these tables will not appear in the PDF version of the help file; see the "TCPIP Cxx Memory Usage.htm" files in the TCPIP documentation folder in the Microchip Application Library help folder. C18 C30 C32
3.3 Peripheral Usage Several microcontroller peripherals can/must be used to implement a TCP/IP stack application. Type Specific/Configurable
Polled/Interrupt Purpose
Timer Timer 0 for PIC18, Timer 1 otherwise
Interrupt.
Used to implement a tick timer
SPI or PMP
Select via #define in HardwareProfile.h. Polled. See Hardware Configuration ( see page 139).
The SPI module is used to drive the ENC28J60 or MRF24WB0M. An ENCX24J600 can be driven by the SPI module or a PMP module.
SPI
Select via #define in HardwareProfile.h. Polled. See External Storage ( see page 139).
Used to interface to an EEPROM or Serial Flash chip, as an option to store web pages for MPFS/MPFS2 ( see page 268) or the AppConfig ( see page 135) structure.
SPI
Select via #define in HardwareProfile.h. Polled. See External Storage ( see page 139).
Used to interface to a serial RAM as a optional socket ( see page 149) allocation method.
57
4
Microchip TCP/IP Stack Help
4 Silicon Solutions One of the first choices to make when designing your application is which hardware layer to use. Microchip supports a number of hardware TCP/IP solutions, each with an integrated MAC and/or PHY. The ENC28J60 and ENCX24J600 are stand-alone Ethernet controller chips, developed by Microchip Technology. The MRF24WB0M is a stand-alone 802.11b wireless transceiver. The PIC18F97J60 is a PIC18 microcontroller with an integrated Ethernet peripheral. The PIC32MX7XX/6XX series of 32-bit microcontrollers are high performance devices with integrated Ethernet MAC peripheral (MII/RMII interface to external PHY). For information about demonstration boards that use these devices, see the Demo Kits ( Feature
ENC28J60
Technology
PIC18F97J60
MRF24WB0M PIC32MX7XX/6XX
Wired Ethernet Wired Ethernet
Wired Ethernet
802.11 Wireless
Wired Ethernet
MAC
Internal
Internal
Internal
Internal
Internal
PHY
Internal (10-Base-T)
Internal (10/100-Base-T)
Internal (10-Base-T)
Internal
External PHY Interface)
24,576
3,808
14,170
Configurable descriptors in Internal RAM (128k of Internal RAM)
RAM (bytes)
Buffer 8,192
ENCX24J600
see page 64) section.
Interface
SPI
SPI, 8 or 16 multiplexed demultiplexed parallel interface
Pins
28
44, 64
Package
Cryptographic Engines
bit None (built-in SPI or Ethernet MAC/PHY)
None MAC)
(built-in
(MII/RMII
Ethernet
64/80/100
36
SOIC, SPDIP, TQFP, QFN SSOP, QFN (6x6 mm)
TQFP
Surface TQFP, QFN (9x9 mm), BGA Mount WiFi I/O module
No
Yes
No
No
No
Yes
No(1)
Yes
Yes
Pre-programmed No(1) MAC address
64/100/121
1: For devices without a pre-programmed MAC address, you may consider using an EEPROM with a built-in MAC address, such as the device family described here ( see page 144).
58
5.2 MPFS2 Utility
Microchip TCP/IP Stack Help
5 Software This section will discuss the computer software applications included with Microchip's TCP/IP Stack. These tools are implemented using the C# or Java programming languages, or both. The C# tools (*.exe) will require the Microsoft® .NET Framework v2.0 to be installed on the local PC. The Java tools (*.jar) require Java Runtime Environment (JRE) 1.6 or later to be installed on the target computer.
5.1 TCP/IP Configuration Wizard The TCP/IP Configuration Wizard is the easiest, safest way to set up firmware (and some hardware) configuration options. It will read and parse configuration settings from a copy of TCPIPConfig.h and then provide a graphical user interface that will easily allow you to view and modify those settings. In addition, if a feature that you enable will require another resource or feature to operate, the additional features will be enabled automatically. The TCP/IP Configuration Wizard will be installed to the Start menu when the TCP/IP Stack is installed. When you launch the configuration wizard, you will be prompted to enter the path to a copy of TCPIPConfig.h and given the opportunity to modify advanced configuration settings. The advanced setting option will give more precise control over stack features, but will also require a greater working knowledge of Microchip's TCP/IP Stack.
5.2 MPFS2 Utility The MPFS2 Utility packages web pages into a format for efficient storage in an embedded system. It is a graphical application for PCs that can generate MPFS2 images for storage in external storage or internal Flash program memory. When used to build MPFS2 images, the MPFS2 Utility also indexes the dynamic variables found. It uses this information to generate HTTPPrint.h, which ensures that the proper callback functions are invoked as necessary. It also stores this index information along with the file in the MPFS2 image, which alleviates the task of searching from the embedded device. Finally, when developing an application that uses external storage, the MPFS2 Utility can upload images to the external 59
5.2 MPFS2 Utility
Microchip TCP/IP Stack Help
Uploading Pre-built MPFS2 Images
storage device using the upload functionality built into the HTTP2 web server or FTP server. The source code for this application is included in the Microchip Applications Libraries installer.
5.2.1 Building MPFS2 Images The MPFS2 Utility has four steps, which are denoted on the left hand side of the dialog. To build an MPFS image, select Start With: Webpage Directory in step 1 and choose the directory in which the web pages are stored.
Step 2 selects the output format. If storing the web pages in external EEPROM or serial Flash, choose the BIN Image output format. If internal program memory will be used, select C18/C32 Image for use with 8-bit and 32-bit parts, or ASM30 Array for 16-bit targets. To store the web pages on a device formatted with the FAT file system without compressing them into an MPFS image, select MDD (see the Demo App MDD Getting Started guide for more information).
Step 3 asks for the MPLAB IDE project directory. The MPFS tool will write the image file to the project directory, and will also update the HTTPPrint.h file there if needed. Select the correct directory so that the right files are modified.
Step 4 controls the upload settings. When external EEPROM or serial flash is used for storage, the option to upload the newly created image to the board is available. Check the box next to Upload Image To to enable this feature. The target host name (or IP address), upload protocol, and upload path may need to be changed to the one chosen when the board was first configured. You may also need to modify the user name and password used to access the secured functionality in your application, like web page upload. Use the Settings button to edit these values. If internal program memory is being used, the image will be compiled in with the project and so direct uploads are not available. Make sure to include the output source file indicated in step 3 as part of the project.
Once all the correct settings have been chosen, click the Generate button to create the image. If uploads are enabled, this will also attempt to upload the file to the device.
5.2.2 Uploading Pre-built MPFS2 Images There are two ways to upload a pre-built image to external storage. The first is described in the Getting Started ( see page 74) section, and involves uploading from the browser directly. The second is to use the MPFS2 Utility to upload the image. You can select HTTP or FTP uploading to match the protocol that your application uses. To use the MPFS2 Utility to upload an image, begin by selecting Start With: Pre-Build MPFS Image in step 1 at the top. 60
5.2 MPFS2 Utility
Microchip TCP/IP Stack Help
MPFS2 Command Line Options
Choose the image file to upload.
Steps 2 and 3 are not required for pre-built images. Proceed directly to step 4 and verify that the upload settings are correct. The target host name (or IP address), upload protocol, and upload path may need to be changed to the one chosen when the board was first configured. You may also need to modify the user name and password used to access the secured functionality in your application, like web page upload. Use the Settings button to edit these values. Once all the settings are correct, click the Upload button. The image will be uploaded to the board.
5.2.3 Advanced MPFS2 Settings The Advanced Settings dialog found in step 2 provides greater control over how files are processed.
The Dynamic Files list indicates which file types to parse for dynamic variables. By default, all files with the extensions htm, html, cgi, or xml are parsed. If an application has dynamic variables in other file types, these types must be added to the list. This field must be a comma-separated list of extensions and file names. The Do Not Compress field indicates which file types should never be compressed. Compressing files with GZIP saves both storage space and transmission time. However, this is only suitable for static content such as CSS or JavaScript. Any files with dynamic variables will automatically be excluded. In addition, any file that the PIC may need to process internally should be excluded. Files included via ~inc:filename~ should not be compressed, nor should any BIB file used for the SNMP module (if present). Additional file types can be added to this list if a custom application will be accessing the MPFS. The GZIP compressor will attempt to shrink all files. In some cases, especially with images, little or no compression is achieved. When this occurs the file is stored as-is in the MPFS image.
5.2.4 MPFS2 Command Line Options To facilitate batch files and automation, the MPFS2 Utility also supports execution from the command line. The syntax is as follows: MPFS2.jar [options] The SourceDir, ProjectDir, and OutputFile options are required and should be enclosed in quotation marks. The OutputFile option will be relative to ProjectDir, and cannot be a full path name. The various option switches are described in the table below: 61
5.4 Microchip TCP/IP Discoverer
Microchip TCP/IP Stack Help
Switch
Short
Description
/BIN
/b
Output a BIN image (Default)
/C18_C32
/c
Output a C18 or C32 image
/ASM30
/s
Output an ASM30 image
/mpfs2
/2
Use the MPFS2 format (Default)
/html "..."
/h "..."
File types to be parsed for dynamic variables (Default: "*.htm, *.html, *.cgi, *.xml")
/xgzip "..."
/z "..."
File types to be excluded from GZIP compression (Default: "*.bib, *.inc")
The command-line interface does not support image uploads. For batch or production uploads, use a tool such as wget to upload the generated BIN image.
5.3 Hash Table Filter Entry Calculator This Hash Table receive filter on the ENC28J60, ENCX24J600, and PIC18F97J60 microcontroller family performs a CRC calculation over the six destination address bytes in a received packet, then uses that value as a pointer into the EHT0-EHT7 registers. If the bit that the pointer points to is set, the packet will be received. The Microchip Hash Table Filter Entry Calculator will determine the bit that must be set in this register bank for a given destination address. If you have a fixed MAC address, known at design time, you can set up your Hash Table receive filter in your code using the value obtained from this tool; otherwise, you must use the SetRXHashTableEntry() function to set it during runtime. To use this tool, specify the address of your device, click calculate, and the CRC value and the corresponding bit will be displayed in the output box.
5.4 Microchip TCP/IP Discoverer The Microchip TCP/IP Discoverer PC project (fomerly known as the Embedded Ethernet Device Discoverer) will aid in embedded product device discovery (with the Announce ( see page 152) protocol) and will demonstrate how to write PC applications to communicate to embedded devices. When the "Discover Devices" button is clicked, this application will transmit a broadcast UDP packet containing the message, "Discovery: Who is out there?" on the local network to port 30303. If any embedded devices with the Announce ( see page 152) protocol enabled are connected to the network, they will respond with a UDP packet containing their host name (NBNS ( see page 287)) and MAC address. The Java source code for this application is also included. This source code should provide a rough idea of how to write a PC-based application to communicate with your embedded devices.
62
5.4 Microchip TCP/IP Discoverer
Microchip TCP/IP Stack Help
63
6.1 Hardware Setup
Microchip TCP/IP Stack Help
Daughter Boards
6 Getting Started This section describes the steps necessary to begin using Microchip's TCP/IP Demo Applications. This section contains specific information for setting up and using the generic TCPIP Demo App ( see page 83). Most of this setup information can be applied to get started with other demo applications as well.
6.1 Hardware Setup The first step to use the stack is to make sure an appropriate development board is configured. To get started, select a platform from the topics presented below.
6.1.1 Daughter Boards Microchip offers four daughter boards that provide different Ethernet functionality to available demo boards. Each board is designed with: • A PICtail™ connector, which enables an interface to the PICDEM.net 2 ( page 67) board (populated with a PIC18 processor)
see page 65) or the PIC18 Explorer (
see
and/or • A PICtail Plus connector, which will allow it to interface to an Explorer 16 ( see page 68) development board (populated with a PIC24, dsPIC33, or PIC32 processor) or a PIC32 Starter Kit ( see page 68). Note that the PICDEM.net 2 is populated by default with an ENC28J60 and a PIC18F97J60. Ethernet PICtail Daughter Board
The Ethernet PICtail Daughter board is populated with an ENC28J60, an RJ-45 connector (with integrated magnetics), and the few other components required for Ethernet operation. It provides a 10-Base-T Ethernet connection for any demo board with a PICtail connector. This daughter board has been largely superseded by the PICDEM.net 2 ( see page 65) for debugging Ethernet applications using the PIC18. Visit the Microchip web site to view the Ethernet PICtail Product Page. Ethernet PICtail Plus Daughter Board
The Ethernet PICtail Plus Daughter Board is the PICtail Plus version of the Ethernet PICtail Daughter Board. It allows the 64
6.1 Hardware Setup
Microchip TCP/IP Stack Help
PICDEM.net 2
interface of an ENC28J60 to any demo board with a PICtail Plus connector. Visit the Microchip web site to view the Ethernet PICtail Plus Daughter Board Product Page. Fast 100Mbps Ethernet PICtail Plus Daughter Board
The Fast 100Mbps Ethernet PICtail Plus Daughter Board provides a method for testing and demonstrating the ENC624J600 Ethernet Controller. The board is designed for flexibility and can be connected to a PICtail or a PICtail plus connector. In addition, it is designed to allow the use of any of the parallel or SPI connection modes featured on the ENC624J600 on the PICtail Plus connector. This daughter board provides 10/100-Base-T functionality. Visit the Microchip web site to view the Fast 100Mbps Ethernet PICtailTM Plus Daughter Board Product Page. Microchip 802.11b WiFi PICtail Plus Daughter Board
The Micorchip 802.11b WiFi PICtail Plus Daughter Board is a demonstration board for evaluating Wi-Fi connectivity on boards with a PICtail or a PICtail Plus connector. The board features the Microchip MRF24WB0MA module, which includes a Wi-Fi transceiver and associated circuit elements. Visit the Microchip Web Site to view more information on Wireless Solutions and the 802.11b WiFi PICtail Product Page..
6.1.2 PICDEM.net 2 Visit the Microchip web site to view the PICDEM.net 2 Product Page. The PICDEM.net 2 development board comes populated with a PIC18F97J60 with an integrated Ethernet controller, as well as a standalone ENC28J60 Ethernet controller. The integrated controller is connected to the left Ethernet jack (closest to the LCD), and the standalone part is connected to the right one. By default the stack is configured to use the integrated controller, so the left port should be connected to the network cable. No other configuration of the board is necessary. The User's Guide that shipped with this development board may refer to an older version of the TCP/IP Stack. This document updates much of that documentation for version 5.36.4.
65
6.1 Hardware Setup
Microchip TCP/IP Stack Help
PICDEM.net 2
Using the Fast Ethernet PICtail By default, this board will use the ENC28J60 or the PIC18F97J60 for Ethernet communication. However, by connecting the Fast Ethernet PICtail to the PICtail connector on the board, you can use it to test the ENC624J600. To use the Fast Ethernet PICtail, insert it as shown in the picture, with header J4 on the PICtail inserted into connector J5 on the demo board.
The Fast Ethernet PICtail is designed to use the SPI communication bus when connected through a PICtail header, so the jumper settings are unused in this configuration, with one exception: the JP2 jumper on the PICtail, labeled ISENSE, should be shorted. The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC624J600 functionality; for manual configuration information, see the ENCX24J600 ( see page 141) configuration page. Using the Microchip 802.11b WiFi PICtail The PICDEM.net 2 can be used to debug wireless functionality by connecting the PICtail as show in the picture, with header J1 on the PICtail inserted into connector J5 on the demo board.
Note if jumper JP3 exists, it must be shorted between pins 2 and 3 when used on this development platform. 66
6.1 Hardware Setup
Microchip TCP/IP Stack Help
PIC18 Explorer
Once your hardware is configured, you can program your board with your preferred demo project. The next few topics ( see page 71) in the Getting Started section of this help file provide a tutorial for setting up the generic TCPIP demo application.
6.1.3 PIC18 Explorer Visit the Microchip web site to view the PIC18 Explorer Product Page. The PIC18 Explorer is for evaluation of high pin-count PIC18 microcontrollers. By connecting a TCP/IP daughter board to it, you can test and debug Ethernet functionality with a variety of PIC18s. The PIC18F97J60 family includes a built-in Ethernet peripheral, making it the default low-cost, PIC18 Ethernet development platform; the PICDEM.net 2 ( see page 65) is the recommended development board for this part. When using the PIC18 Explorer, ensure that jumpers JP2 and JP3 are shorted to enable the LCD and EEPROM, and switch S4 is configured to properly select the on-board PIC or the ICE setting, as your application requires.
Using the Ethernet PICtail Unlike the PICDEM.net 2, the PIC18 Explorer does not include an ENC28J60 on the board. To enable testing and debugging using the ENC28J60, you must connect ( see page 168) an Ethernet PICtail, as shown in the picture (insert header J2 into connector J3 on the demo board).
When using this configuration, short pins 2 and 3 on jumper J9, to indicate that the PIC18 Explorer is providing a 5V power 67
6.1 Hardware Setup
Microchip TCP/IP Stack Help
Explorer 16 and PIC32 Starter Kit
supply. The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC28J60 functionality; for manual configuration information, see the ENC28J60 ( see page 140) configuration page. Using the Fast Ethernet PICtail By connecting the Fast Ethernet PICtail to the PICtail connector on the board, you can use it to test the ENC624J600. To use the Fast Ethernet PICtail, insert it as shown in the picture, with header J4 on the PICtail inserted into connector J3 on the demo board.
The Fast Ethernet PICtail is designed to use the SPI communication bus when connected through a PICtail header, so the jumper settings are unused in this configuration, with one exception: the JP2 jumper on the PICtail, labeled ISENSE, should be shorted. The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC624J600 functionality; for manual configuration information, see the ENCX24J600 ( see page 141) configuration page. Using the Microchip 802.11b WiFi PICtail The PIC18 Explorer can be used to debug wireless functionality by connecting the PICtail as show in the picture, with header J1 on the PICtail inserted into connector J3 on the demo board.
Note if jumper JP3 exists, it must be shorted between pins 2 and 3 when used on this development platform. Once your hardware is configured, you can program your board with your preferred demo project. The next few topics ( see page 71) in the Getting Started section of this help file provide a tutorial for setting up the generic TCPIP demo application.
6.1.4 Explorer 16 and PIC32 Starter Kit Visit the Microchip web site to view the Explorer 16 Product Page and the PIC32 Starter Kit Product Page. The Explorer 16 board is an all-purpose demonstration and development board for 16-bit and 32-bit parts. It can be expanded for TCP/IP support using the Ethernet PICtail Plus, Fast 100Mbps Ethernet PICtail Plus, or 802.11b WiFi PICtail Plus daughter board. Before using the Explorer 16, check that:
68
6.1 Hardware Setup
Microchip TCP/IP Stack Help
Explorer 16 and PIC32 Starter Kit
1. Switch S2 selects PIM 2. Jumper J7 selects PIC24 (even though the label reads PIC24, this jumper setting selects the programming signals to any PIC on the Explorer 16).
The PIC32 Starter Kit performs a similar function for 32-bit PIC32 parts. By using the PIC32 I/O Expansion Board you can connect ( see page 168) the same PICtail Plus board that connect ( see page 168) to the Explorer 16.
Using the Ethernet PICtail Plus To enable testing and debugging of the ENC28J60 on these boards, you must connect ( see page 168) an Ethernet PICtail Plus, as shown in the picture (insert header J2 into the upper card-edge connector J5 (Explorer 16) or J4 (I/O Expansion Board)). Note that for some demos, the Ethernet PICtail Plus will need to be inserted into the center card-edge connector of the PICtail Plus connector to use the SPI2 module. See the Demo Compatibility Table ( see page 79) for more information.
69
6.1 Hardware Setup
Microchip TCP/IP Stack Help
Explorer 16 and PIC32 Starter Kit
The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC28J60 functionality; for manual configuration information, see the ENC28J60 ( see page 140) configuration page. Using the Fast Ethernet PICtail Plus By connecting the Fast 10/100 Ethernet PICtail Plus to the PICtail Plus connector on your board, you can use it to test the ENC624J600. The Fast Ethernet PICtail Plus can be used with these boards in either serial (SPI) or parallel communication mode. For serial mode, connect ( see page 168) header J2 of the daughter board to connector J5 (Explorer 16) or J4 (I/O Expansion Board), as seen in the pictures. When operating in serial mode, the jumpers on the Fast Ethernet PICtail are unused, with one exception: the JP2 jumper on the PICtail, labeled ISENSE, should be shorted.
To use the Fast Ethernet PICtail Plus board in parallel mode, insert header J1 into connector J5 of the Explorer 16 or J4 of the I/O Expansion Board, as seen in the pictures. In this configuration, the jumpers must be shorted or opened corresponding to the parallel communication mode being used. A matrix outlining which jumper connections must be made for the jumpers labeled PSPCFG3, PSPCFG2, PSPCFG1&4, PMA to AD, and PMA to A is printed on the back side of the daughter board.
The pre-compiled and pre-configured versions of the demo that correspond to this setup are already written to enable ENC624J600 functionality; for manual configuration information, see the ENCX24J600 ( see page 141) configuration page. Using the Microchip 802.11b WiFi PICtail The Explorer 16 and PIC32 Starter Kit can be used to debug wireless functionality by connecting the PICtail as show in the pictures, with header J2 on the PICtail inserted into the top slot of connector J5 (Explorer 16) or J4 (I/O Expansion Board) on the demo boards.
70
6.2 Programming and First Run
Microchip TCP/IP Stack Help
Note if jumper JP3 exists, it must be shorted between pins 1 and 2 when used on this development platform. Once your hardware is configured, you can program your board with your preferred demo project. The next few topics ( see page 71) in the Getting Started section of this help file provide a tutorial for setting up the generic TCP/IP demo application.
6.1.5 PIC24FJ256DA210 Dev Board Visit the Microchip web site to view the PIC24FJ256DA210 Development Kit Product Page. The PIC24FJ256DA210 Development Kit is a low cost and efficient development kit to evaluate the features and performance of the PIC24FJ256DA210 with integrated graphics, mTouch™ and USB.
You can add network connectivity to this demo board by inserting an Ethernet PICtail Plus, Fast Ethernet PICtail Plus, or Microchip 802.11b WiFi PICtail into the PICtail Plus connector on the demo board. The method for doing this is functionally identical to the method used for the Explorer 16 and PIC32 Starter Kit ( see page 68).
6.2 Programming and First Run Once the hardware is configured (
see page 64), you are ready to program the device for the first time.
Project Setup Open a session of the MPLAB IDE. 71
6.3 Configure your WiFi Access Point
Microchip TCP/IP Stack Help
1. From the "File" menu, select "Import." Browse to the Precompiled Hex subdirectory in your demo project directory and select the *.hex file that matches your hardware setup. The hex file names describe the hardware that the file has been compiled for. For example, the file "Microchip Solutions v2011-06-02\TCPIP\Demo App\Precompiled Hex\C18-PICDN2_ETH97 18F97J60.hex" corresponds to the generic TCP/IP Demo application for the PIC18F97J60 on the PICDEM.net 2, using the PIC's internal Ethernet module. A document enumerating the abbreviations used in the hex file and project file names is available in the Microchip Solutions v20xx-xx-xx/Help directory. 2. Verify that the MPLAB IDE processor target selection and linker script (if one is present) match the part on your demonstration board (ex: PIC18F97J60). Note that the projects and source code used to build each hex file are present in the project directory. The hardware and firmware configuration files used to build each project are included in the Configs subdirectory. Programming Select your device programmer from the Programmer menu in MPLAB, and then use the Program shortcut button or the Program menu option to program the code you imported to your board. Clearing the EEPROM The TCP/IP Stack stores network configuration settings (such as the host name, MAC address, default static IP addresses, SNMP strings, WiFi network name (SSID), etc) in external EEPROM on the board. The demo project will detect if the default values have been changed in the EEPROM, and if so, use the new values. If not, the demo will use the default values configured in TCPIPConfig.h and WF_Config.h. Checksums stored in the EEPROM are used to determine if the structures stored in EEPROM are valid. Manually clearing the EEPROM will allow the demo to resume using the default settings. Use the following procedure to clear the EEPROM: 1. Make sure the development board is programmed and not in debug mode 2. Disconnect the MPLAB® ICD 2/3 or MPLAB REAL ICETM from the board 3. Press and hold BUTTON0 (RD13/S4 on Explorer 16 or RB3/S5 on PICDEM.netTM 2) 4. Press and release the MCLR button 5. Continue holding BUTTON0 until several LEDs flash indicating that EEPROM has been cleared. This takes about 4 seconds. 6. Release BUTTON0 7. Press and release MCLR again to reset the software Once you see LED0 (right-most LED) blinking, the software is running and ready for use. If you are using the MRF24WB0M WiFi PICtail, you'll need to configure your wireless access point ( all Ethernet devices, Connect your Development Board ( see page 74) to your network.
see page 72) first. For
6.3 Configure your WiFi Access Point To run the Wi-Fi demos with the MRF24WB0M PICtail, you'll also need to setup a wireless access point. As an example, this guide will walk through the setup of a Linksys WRT54G2 access point. Access Point Browser GUI The Linksys, along with many other popular router brands, uses a built-in webserver on the router to administer the network (both wired and wireless). Please consult the documentation that came with your router for more information on configuration and setup. For a list of known compatible routers refer to section "Access Point Compatibility" ( see page 601). To gain access to this web page, you'll need to point your browser to http://192.168.1.1. By default, the username field is left blank, and the password is admin.
72
6.3 Configure your WiFi Access Point
Microchip TCP/IP Stack Help
Wireless Setup Along the top of the webpage, there should be many tabs for all the different features of the access point. One of the tabs should read "Wireless". After clicking the tab, you will be presented with the Wi-Fi protected setup page. You'll need to click the manual tab to be able to enter your own wireless settings to match the demo.
The out of box demo is looking for an AP with the following parameters (note that the SSID is case sensitive): SSID
MicrochipDemoAP
Security
None
Channel
Either 1, 6, or 11
You should have settings similar to the following:
73
6.5 Uploading Web Pages
Microchip TCP/IP Stack Help
Once the network is setup, you can connect your device to the network (
see page 74).
6.4 Connecting to the Network All devices on a TCP/IP network must be assigned an IP address ( see page 145). Whereas the MAC address ( see page 144) is the hardware address of the device, the IP address is a software address. The DHCP (Dynamic Host Configuration Protocol) allows this assignment to take place automatically (for more address information and configuration options, see the Addresses ( see page 144) topic). The demo application comes with both a DHCP server and DHCP client configured. This allows the board to connect ( see page 168) to most networks without configuration. If a free Ethernet port is available on a nearby router, switch, or wall plate, the board can be connected directly using any standard straight-through Ethernet cable. Under this configuration, the board will attempt to obtain an IP address from your network's DHCP server. If this method is not possible, a crossover Ethernet cable can be used to connect ( see page 168) the board directly to a PC's Ethernet port. Using this configuration, the board will act as its own DHCP server and will assign a single IP address to the computer. (The Fast 100Mbps Ethernet PICtail Plus and some newer PCs do not require a special crossover cable, so any Ethernet cable can be used.) Connect the development board to the network and wait for the link LED on the Ethernet jack to light up. The board is now on the network and capable of communicating with other devices. If the link LED on the Ethernet jack does not light, your board cannot link to the network. Ensure that you have selected the proper cable, and try switching from a straight-through to a crossover cable, or vice versa. Now that the board is online, you can Upload the Demo Web Pages (
see page 74).
6.5 Uploading Web Pages Web pages are stored as an MPFS2 ( see page 268) image. This image can be placed in either external non-volatile storage ( see page 139) (EEPROM or SPI Flash), or in the microcontroller's internal Flash program memory. For this example, the EEPROM chip (25LC256) on your demo board will be programmed with a pre-built MPFS2 BIN image. This location can be changed via a compile-time option in TCPIPConfig.h. The target application on the development board must be running for this procedure to work. Make sure the right most status LED is blinking. Each hex file is configured to provide a Host Name for your development board. This will be the name by which your board is accessed. In the default hex files, the host name is mchpboard, so you board can be accessed at http://mchpboard. This 74
6.6 Accessing the Demo Application
Microchip TCP/IP Stack Help
host name uses the NetBIOS Name Service ( see page 287). It is only available on your local subnet, and will not be accessible from the Internet. Note that this service is not supported by all operating systems. If you have difficulty accessing your board, try using the IP address shown on the LCD screen instead (e.g. access the board at http://192.168.1.101). You can also determine the IP address by using the Microchip TCP/IP Discoverer ( see page 62). Open a web browser and access the board at http://mchpboard/mpfsupload. This form will allow web pages stored on the device to be updated. If you mistype this URL, the board will provide a default HTTP 404 error page with a link to the MPFS Upload page. This default 404 page will not appear if you've configured your browser to override custom error pages (e.g. by checking "Show friendly HTTP error messages" in Internet Explorer 7's internet options menu). Select the file MPFSImg2.bin from the TCPIP\Demo App folder as shown below. This update method is only available when using external storage.
When the Upload button is clicked, the MPFS image is sent to the board and programmed into the EEPROM. As this happens, the activity LED on the Ethernet jack will blink. Once the browser reports that the upload has completed, click the link provided within the status message to access the board's web pages. You can now Access the Demo Application (
see page 75).
6.6 Accessing the Demo Application The board is now accessible at the mchpboard host name or at the board's IP address. When accessed in a web browser, a real-time update of the board's controls is displayed. The demo application will show off several features, and will explain how to modify the web pages and application to suit various needs.
75
6.7 Configuring WiFi Security
Microchip TCP/IP Stack Help
If you attempt to access the Network Configuration or SNMP Configuration web pages from the red menu on the left, you will be prompted for a username and password. The default username is "admin" and the default password is "microchip". More information is available on the Authentication ( see page 86) web page, or in the HTTP2 server authentication ( see page 233) help topic. Some features of the default demo application may not be available on certain hardware platforms. For more information, see the TCPIP Demo App Features by Hardware Platform ( see page 83) topic. For information about how to use each feature of the TCP/IP Demo Application, consult the subtopics in the TCP/IP Demo Application Demo Modules ( see page 84) topic. Once you have finished exploring the demo application, you can proceed to the Stack API ( more about the stack and start developing your own application.
see page 152) section to learn
If you are exploring the Wi-Fi demo applications and want to set up security, you can get more information on the WLAN security page ( see page 76).
6.7 Configuring WiFi Security The MRF24WB0M can be configured to connect ( see page 168) to wireless networks with encryption enabled. The MRF24WB0M supports WEP (40-bit and 104-bit), as well as WPA (TKIP) and WPA2 (TKIP/AES). Device Security Modes Security settings for the MRF24WB0M are located in the file WF_Config.h. To enable security features the #define preprocessor definition for MY_DEFAULT_WIFI_SECURITY_MODE must be defined as one of the following options:
76
6.7 Configuring WiFi Security
Microchip TCP/IP Stack Help
WF_SECURITY_WEP_40
40-bit WEP security. This equates to 5 ASCII characters or 10 hex digits. MY_DEFAULT_WEP_KEYS_40 contains up to four keys that can be programmed (default is key 0).
WF_SECURITY_WEP_104
104-bit WEP security. This equates to 13 ASCII characters or 26 hex digits. MY_DEFAULT_WEP_KEYS_104 contains up to four keys that can be programmed (default is key 0).
Uses the 32 bytes in MY_DEFAULT_PSK as the key to join the network. These values are generated from a hash of the SSID name and WPA passphrase. For the purpose of the demo, the 32-bytes in MY_DEFAULT_PSK in WF_Config.h correspond to an SSID of "MicrochipDemoAP" and passphrase "Microchip 802.11 Secret PSK Password".
WF_SECURITY_WPA_WITH_PASS_PHRASE Instructs the MRF24WB0M to generate the 32 byte PSK using the SSID and passphrase. The default in WF_Config.h corresponds to an WF_SECURITY_WPA2_WITH_PASS_PHRASE WF_SECURITY_WPA_AUTO_WITH_PASS_PHRASE SSID of "MicrochipDemoAP" and passphrase "Microchip 802.11 Secret PSK Password". Note that it takes approximately 30 seconds for the MRF24WB0M to calculate this value[1]. Note: Some routers try to increase the random nature of the WEP key by adding an additional layer that will convert an ASCII passphrase into a hexadecimal key. The MRF24WB0M PICtail will require a hexadecimal key, no matter which way it is generated. Access Point Security Settings The access point will also need to be changed to match the same security settings. Wireless security settings can be found in the "Wireless Security" tab under the main "Wireless" tab (example shows a Linksys WRT5G2). The drop-down box for security has all the different security options. Note that for WPA/WPA2, the MRF24WB0M only supports personal security levels (as opposed to enterprise, which is not supported).
[1]: Once the 32-byte PSK is calculated, it can be retrieved by the host from the MRF24WB0M. The host can then save this key to external non-volatile memory. On future connection attempts, the host can program the MRF24WB0M with the 77
6.7 Configuring WiFi Security
Microchip TCP/IP Stack Help
WF_SECURITY_*_WITH_KEY options, provide the saved key, and not have to wait 30 seconds to reconnect to the network. Pre-generated PSK You also have the option to pre-generate the PSK and use the 32-byte PSK directly in the source code. One handy tool to generate the PSK can be found online at the Wireshark Foundation http://www.wireshark.org/tools/wpa-psk.html. The Wireshark website can generate the expected 32-byte PSK key with the SSID name and the passphrase. You can then use these values in the variable MY_DEFAULT_PSK in TCPIPConfig.h.
78
7.1 Demo Compatibility Table
Microchip TCP/IP Stack Help
7 Demo Information This section describes Microchip's TCP/IP Demo projects, including information about demo-hardware compatibility. For information about how to load and configure the demos, please consult the Getting Started section.
7.1 Demo Compatibility Table Each stack demonstration project comes with several predefined, tested configurations. Pre-built hex files for each demo are available in the Precompiled Hex subdirectory in that demo's project folder (i.e. the files for Demo App are located in \Microchip Solutions v20xx-xx-xx\TCPIP\Demo App\Precompiled Hex). This section will specify the combinations of demo boards, processors, MAC/PHY layers, and communication buses that are set up to work by default. TCPIP Demo App (
see page 83)
Demo Board
Processor
MAC/PHY Layer
Comm. Bus
Notes
PIC18 Explorer
18F87J11
ENC28J60
SPI
Requires silicon revision A4 or later.
PIC18 Explorer
18F87J11
ENCX24J600
SPI
PIC18 Explorer
18F87J11
MRF24WB0M
SPI
PIC18 Explorer
18F87J50
ENC28J60
SPI
PIC18 Explorer
18F87J50
ENCX24J600
SPI
PIC18 Explorer
18F87J50
MRF24WB0M
SPI
PIC18 Explorer
18F8722
ENC28J60
SPI
PIC18 Explorer
18F8722
ENCX24J600
SPI
PIC18 Explorer
18F8722
MRF24WB0M
SPI
PICDEM.net 2
18F97J60
ETH97J60
-
PICDEM.net 2
18F97J60
ENC28J60
SPI
PICDEM.net 2
18F97J60
ENCX24J600
SPI
PICDEM.net 2
18F97J60
MRF24WB0M
SPI
Explorer 16
24FJ128GA010
ENC28J60
SPI
Explorer 16
24FJ128GA010
ENCX24J600
SPI
Explorer 16
24FJ128GA010
MRF24WB0M
SPI
Explorer 16
24FJ128GA010
ENCX24J600
PSP Indirect
Explorer 16
24FJ256GA110
ENC28J60
SPI2
Explorer 16
24FJ256GA110
ENCX24J600
SPI2
Explorer 16
24FJ256GA110
ENCX24J600
PSP Indirect
Explorer 16
24FJ256GA110
MRF24WB0M
SPI2
5
5
79
7.1 Demo Compatibility Table
Microchip TCP/IP Stack Help
Explorer 16
24FJ256GB110
ENC28J60
SPI
Explorer 16
24FJ256GB110
ENCX24J600
SPI
Explorer 16
24FJ256GB110
ENCX24J600
PSP Indirect
Explorer 16
24FJ256GB110
MRF24WB0M
SPI
Explorer 16
24FJ256GB210
ENC28J60
SPI
Explorer 16
24FJ256GB210
ENCX24J600
SPI
Explorer 16
24FJ256GB210
ENCX24J600
PSP Indirect Bitbang
Explorer 16
24FJ256GB210
MRF24WB0M
SPI
Explorer 16
33FJ256GP710
ENC28J60
SPI
Explorer 16
33FJ256GP710
ENCX24J600
SPI
Explorer 16
33FJ256GP710
ENCX24J600
PSP Indirect
Explorer 16
33FJ256GP710
MRF24WB0M
SPI
Explorer 16
32MX360F512L
ENC28J60
SPI
Explorer 16
33EP512MU810
ENC28J60
SPI2
Explorer 16
24EP512GU810
ENC28J60
SPI2
Explorer 16
32MX360F512L
ENCX24J600
SPI
Explorer 16
32MX360F512L
ENCX24J600
PSP Indirect
Explorer 16
32MX360F512L
ENCX24J600
PSP 9
Explorer 16
32MX360F512L
MRF24WB0M
SPI
Explorer 16
32MX460F512L
ENC28J60
SPI
Explorer 16
32MX460F512L
ENCX24J600
SPI
Explorer 16
32MX460F512L
MRF24WB0M
SPI
Explorer 16
32MX795F512L
ENC28J60
SPI
Explorer 16
32MX795F512L
ENCX24J600
SPI
Explorer 16
32MX795F512L
MRF24WB0M
SPI
PIC24FJ256DA210 Board
Development 24FJ256DA210
ENC28J60
SPI
PIC24FJ256DA210 Board
Development 24FJ256DA210
ENCX24J600
SPI
PIC24FJ256DA210 Board
Development 24FJ256DA210
ENCX24J600
PSP Indirect Bitbang
PIC24FJ256DA210 Board
Development 24FJ256DA210
MRF24WB0M
SPI
PIC32 General Purpose Starter Kit 32MX360F512L (DM320001)
ENC28J60
SPI
PIC32 General Purpose Starter Kit 32MX360F512L (DM320001)
ENCX24J600
SPI
PIC32 General Purpose Starter Kit 32MX360F512L (DM320001)
ENCX24J600
PSP Indirect
PIC32 General Purpose Starter Kit 32MX360F512L (DM320001)
MRF24WB0M
SPI
5
5
5
5
5
5
80
7.1 Demo Compatibility Table
Microchip TCP/IP Stack Help
PIC32 USB Starter Kit (DM320003_2)
32MX795F512L
ENC28J60
SPI2
PIC32 USB (DM320003_2)
32MX795F512L
ENCX24J600
SPI2
PIC32 USB (DM320003_2)
32MX795F512L
ENCX24J600
PSP Indirect
PIC32 USB (DM320003_2)
32MX795F512L
ENCX24J600
PSP 9
PIC32 USB (DM320003_2)
32MX795F512L
MRF24WB0M
SPI2
PIC32 Ethernet Starter Kit
32MX795F512L
Internal MAC, National DP83848C PHY
dsPIC33E USB Starter Kit
33EP512MU810
ENCX24J600
SPI2
dsPIC33E USB Starter Kit
33EP512MU810
ENCX24J600
PSP 5
dsPIC33E USB Starter Kit
33EP512MU810
ENCX24J600
PSP Indirect
dsPIC33E USB Starter Kit
33EP512MU810
MRF24WB0M
SPI2
PIC24E USB Starter Kit
24EP512GU810
ENCX24J600
SPI2
PIC24E USB Starter Kit
24EP512GU810
ENCX24J600
PSP5
PIC24E USB Starter Kit
24EP512GU810
ENCX24J600
PSP Indirect
PIC24E USB Starter Kit
24EP512GU810
MRF24WB0M
SPI2
TCPIP WebVend (
5
5
5
see page 123)
Demo Board
Processor
MAC/PHY Layer
Comm. Bus
PICDEM.net 2
18F97J60
ENC28J60
SPI
PICDEM.net 2
18F97J60
ETH97J60
-
Explorer 16
24FJ128GA010
ENC28J60
SPI
Explorer 16
24FJ128GA010
ENCX24J600
SPI
Explorer 16
24FJ128GA010
MRF24WB0M
SPI
Explorer 16
33FJ256GP710
ENC28J60
SPI
Explorer 16
33FJ256GP710
ENCX24J600
SPI
Explorer 16
33FJ256GP710
MRF24WB0M
SPI
Explorer 16
32MX360F512L
ENC28J60
SPI
Explorer 16
32MX360F512L
ENCX24J600
SPI
Explorer 16
32MX360F512L
MRF24WB0M
SPI
Explorer 16
32MX460F512L
ENC28J60
SPI
Explorer 16
32MX460F512L
ENCX24J600
SPI
Explorer 16
32MX460F512L
MRF24WB0M
SPI
Explorer 16
32MX795F512L
ENC28J60
SPI
Explorer 16
32MX795F512L
ENCX24J600
SPI
Explorer 16
32MX795F512L
MRF24WB0M
SPI
TCPIP WiFi EasyConfig Demo App (
Notes
see page 130)
Demo Board
Processor
MAC/PHY Layer
Comm. Bus
Explorer 16
24FJ128GA010
MRF24WB0M
SPI
Notes
81
7.1 Demo Compatibility Table
Microchip TCP/IP Stack Help
Explorer 16
33FJ256GP710
MRF24WB0M
SPI
Explorer 16
32MX360F512L
MRF24WB0M
SPI
Explorer 16
32MX460F512L
MRF24WB0M
SPI
Explorer 16
32MX795F512L
MRF24WB0M
SPI
MRF24WB0M
SPI
PIC24FJ256DA210 Board
Development PIC24FJ256DA210
TCPIP WiFi Console Demo App (
see page 124)
Demo Board
Processor
MAC/PHY Layer
Comm. Bus
PICDEM.net 2
18F97J60
MRF24WB0M
SPI
Explorer 16
24FJ128GA010
MRF24WB0M
SPI
Explorer 16
33FJ256GP710
MRF24WB0M
SPI
Explorer 16
32MX360F512L
MRF24WB0M
SPI
Explorer 16
32MX460F512L
MRF24WB0M
SPI
Explorer 16
32MX795F512L
MRF24WB0M
SPI
MRF24WB0M
SPI
PIC24FJ256DA210 Board
Development PIC24FJ256DA210
TCPIP Internet Radio App (
see page 123)
Demo Board
Processor
MAC/PHY Layer
Comm. Bus
Internet Radio Board
18F67J60
ENC28J60
SPI
TCPIP Internet Bootloader (
Notes
Notes
see page 117)
Demo Board
Processor
MAC/PHY Layer
Comm. Notes Bus
N/A
18F66J60
ETH97J60
-
N/A
18F66J60
ETH97J60
-
N/A
18F66J65
ETH97J60
-
N/A
18F66J65
ETH97J60
-
N/A
18F67J60
ETH97J60
-
N/A
18F67J60
ETH97J60
-
N/A
18F86J60
ETH97J60
-
N/A
18F86J60
ETH97J60
-
N/A
18F86J65
ETH97J60
-
N/A
18F86J65
ETH97J60
-
N/A
18F87J60
ETH97J60
-
N/A
18F87J60
ETH97J60
-
N/A
18F96J60
ETH97J60
-
N/A
18F96J60
ETH97J60
-
N/A
18F96J65
ETH97J60
-
N/A
18F96J65
ETH97J60
-
N/A
18F97J60
ETH97J60
-
Extended Instruction Mode
Extended Instruction Mode
Extended Instruction Mode
Extended Instruction Mode
Extended Instruction Mode
Extended Instruction Mode
Extended Instruction Mode
Extended Instruction Mode
82
7.2 Available Demos
N/A
Microchip TCP/IP Stack Help
18F97J60
TCPIP MDD Demo App (
ETH97J60
-
Demo App
Extended Instruction Mode
see page 132)
Demo Board
Processor
MAC/PHY Layer
Comm. Notes Bus
Explorer 16
PIC24FJ256GB110 ENC28J60
SPI
Uses USB Thumb Drive as a storage medium for web pages.
Explorer 16
PIC24FJ128GA010 ENC28J60
SPI
Uses SD Card as a storage medium for web pages.
Google Map For information on the Google Map demo compatibility, see the file "Getting Started - Running the Graphics Google Map Demo" in the Combo Demos/Google Map directory in your Microchip Applications Library installation directory.
7.2 Available Demos The TCP/IP Stack comes with several example applications. These applications are described in the following sections.
7.2.1 Demo App The TCPIP\Demo App project folder contains the main demo application for the Microchip TCP/IP Stack. Besides showing example applications using the web server, e-mail client, SNMP server, and more, this application also includes examples for implementing custom application layers. Details about these applications are provided here. For a list of pre-tested demo hardware configurations, please consult the Demo Compatibility Table ( see page 79). Unspecified hardware configurations may also be useable with the Demo App, but some additional configuration may be necessary. Some demo features are disabled in certain Demo App projects to support the associated hardware platform and TCP/IP controller. Please consult the following table to determine which features are available on which configurations:
7.2.1.1 TCPIP Demo App Features by Hardware Platform Some hardware platforms cannot support all of the features implemented in the TCP/IP Demo Application. The following table outlines which features are available for each combination of demo board and MAC/PHY layer supported natively by the TCP/IP Demo App. Note that this table will not appear in the PDF version of the help file; see the "TCPIP Demo App Features.htm" file in the TCPIP documentation folder in the Microchip Application Library help folder. NVM Storage A board with Non-Volatile Memory can modify and save its configuration variables at runtime. In the TCP/IP Demo App, this allows you to change the board name, IP Address ( see page 144), wireless SSID, wireless security, or other configuration parameters via a web page interface. The data will be written to SPI Flash or EEPROM and then used to reinitialize the board if it is reset. A board without this feature will always use the default settings after power-up. Buttons and LEDs The TCP/IP Stack-compatible demo boards have a variable number of buttons and LEDs. By default, the TCP/IP Demo App is configured to display and accept ( see page 166) input from 8 LEDs and 4 buttons on the demo's index page; the buttons and LEDs used depend on what is available on the board. 83
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
7.2.1.2 Demo Modules Modules Name
Description
Web Page Demos (
see page 84)
E-mail (SMTP) Demo (
Generic TCP Client (
see page 93)
see page 94)
Generic TCP Server ( Ping (ICMP) Demo (
see page 97) see page 98)
SNMP Server (Agent) (
see page 100)
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 87) topic. Demonstrates how to build a TCP Client application through an HTTP client example. Demonstrates how to build a TCP server application Demonstrates how to build a Ping client. 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.
7.2.1.2.1 Web Page Demos Functions Name
Description
HTTPPostSNMPCommunity ( see page 89)
This is function HTTPPostSNMPCommunity.
HTTPPostConfig ( page 90)
Processes the configuration form on config/index.htm
see
HTTPPostDDNSConfig ( see page 90)
Parsing and collecting http data received from http form.
HTTPPostEmail ( 91)
Processes the e-mail form on email/index.htm
see page
HTTPPostLCD ( 91)
see page
Processes the LCD form on forms.htm
HTTPPostMD5 ( 92)
see page
Processes the file upload form on upload.htm
Variables Name DDNSData ( lastFailure ( lastSuccess (
Description see page 92) see page 93) see page 93)
RAM allocated for DDNS parameters Stick status message variable. See lastSuccess (
see page 93) for details.
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 86), processing web forms (using HTTP GET and POST), and providing status information through the output of dynamic variables.
84
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
7.2.1.2.1.1 Dynamic Variables Module Web Page Demos (
see page 84)
Description Overview This section describes how to view dynamic variables in the TCP/IP Demo App HTTP2 demo. For information about how to implement dynamic variables in your own page, see the HTTP2 dynamic variables topic ( see page 228). 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 83) topic for more information.
3. Observe the current Stack Version and Build Date in the top center of the Overview Page. 4. Navigate to the Dynamic Variables page using the navigation panel on the left of the page. 5. Observe the Build Date and Time, LED state, stack version, and current IP address- these variables are output to this page dynamically when it's downloaded by the browser. Exercises You can optionally complete the exercises described on the Dynamic Variables page. You may want to read the HTTP2 dynamic variables topic ( see page 228) 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.
85
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
7.2.1.2.1.2 Authentication Module Web Page Demos (
see page 84)
Description Overview This section describes how to use the authentication demo in the TCP/IP Demo App HTTP2 demo. For information about how to implement authentication in your own page, see the HTTP2 Authentication topic ( see page 233). 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 238) function.
3. Change the values being compared to the function inputs to a username and password of you choosing. 4. Rebuild your project and program your board.
7.2.1.2.1.3 Forms using GET Module Web Page Demos (
see page 84)
Description Overview This section describes how to use web forms in the TCP/IP Demo App HTTP2 demo. For information about how to implement forms in your own page, see the HTTP2 form processing topic ( see page 230). 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 83) topic for more information. 3. Navigate to the Form Processing page using the navigation panel on the left of the page. 86
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
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 230) 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 ( for the forms.htm file.
see page 239) function. Locate the section of code the processes GET arguments
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 Web Page Demos (
see page 84)
Description Overview This section describes how to use web forms in the TCP/IP Demo App HTTP2 demo. For information about how to implement forms in your own page, see the HTTP2 form processing topic ( see page 230). 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. 87
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
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 168) 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 375) 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 Web Page Demos (
see page 84)
Description Overview This section describes how to use the cookie demo in the TCP/IP Demo App HTTP2 demo. For information about how to implement cookies in your own page, see the HTTP2 Cookies topic ( see page 235). 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 228), GET ( see page 230), and cookie ( see page 235) topics first. 88
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
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 ( "not implemented" string with a dynamic variable to output the data from the cookie.
see page 219) the
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 ( 239) function and find the code that handles GET method inputs from cookies.htm.
see page
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"); if(ptr) TCPPutString(sktHTTP, ptr); else TCPPutROMString(sktHTTP, (ROM BYTE*)"not set"); return; } 7. Compile your web page using the MPFS2 Utility and upload it to your board. You may receive a warning that your dynamic variables have changed in your page. 8. Rebuild your project and program your board. 9. Verify that both cookies can be set.
7.2.1.2.1.6 Functions Functions Name
Description
HTTPPostSNMPCommunity ( see page 89)
This is function HTTPPostSNMPCommunity.
HTTPPostConfig ( page 90)
Processes the configuration form on config/index.htm
see
HTTPPostDDNSConfig ( see page 90)
Parsing and collecting http data received from http form.
HTTPPostEmail ( 91)
Processes the e-mail form on email/index.htm
see page
HTTPPostLCD ( 91)
see page
Processes the LCD form on forms.htm
HTTPPostMD5 ( 92)
see page
Processes the file upload form on upload.htm
Module Web Page Demos (
see page 84)
7.2.1.2.1.6.1 HTTPPostSNMPCommunity Function File CustomHTTPApp.c
89
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
C static HTTP_IO_RESULT HTTPPostSNMPCommunity(); Description This is function HTTPPostSNMPCommunity.
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 Return Values Return Values
Description
HTTP_IO_DONE
all parameters have been processed
HTTP_IO_NEED_DATA
data needed by this function has not yet arrived
7.2.1.2.1.6.3 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 92)) 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 237) is loaded.
Return Values Return Values
Description
HTTP_IO_DONE
Finished with procedure
HTTP_IO_NEED_DATA
More data needed to continue, call again later 90
7.2 Available Demos HTTP_IO_WAITING
Microchip TCP/IP Stack Help
Demo App
Waiting for asynchronous process to complete, call again later
7.2.1.2.1.6.4 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 plain- text encoding. The third section has headers indicating an attached file, along with its name and type. All sections are separated by a boundary string, which cannot appear anywhere else in the message. Preconditions None Return Values Return Values
Description
HTTP_IO_DONE
the message has been sent
HTTP_IO_WAITING
the function is waiting for the SMTP process to complete
HTTP_IO_NEED_DATA
data needed by this function has not yet arrived
7.2.1.2.1.6.5 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 Return Values
Description
HTTP_IO_DONE
the parameter has been found and saved
HTTP_IO_WAITING
the function is pausing to continue later
HTTP_IO_NEED_DATA
data needed by this function has not yet arrived
91
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
Section Function Prototypes and Memory Globalizers
7.2.1.2.1.6.6 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 data is trashed in this process, allowing us to accept ( see page 166) files of arbitrary size, not limited by RAM. Also notice that the data buffer is used as an arbitrary storage array for the result. The ~uploadedmd5~ callback reads this data later to send back to the client. Preconditions None Return Values Return Values
Description
HTTP_IO_DONE
all parameters have been processed
HTTP_IO_WAITING
the function is pausing to continue later
HTTP_IO_NEED_DATA
data needed by this function has not yet arrived
7.2.1.2.1.7 Variables Module Web Page Demos (
see page 84)
Variables Name DDNSData ( lastFailure ( lastSuccess (
Description see page 92) see page 93) see page 93)
RAM allocated for DDNS parameters Stick status message variable. See lastSuccess (
see page 93) for details.
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.1.7.1 DDNSData Variable File CustomHTTPApp.c C BYTE DDNSData[100];
92
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
Description RAM allocated for DDNS parameters
7.2.1.2.1.7.2 lastFailure Variable File CustomHTTPApp.c C BOOL lastFailure = FALSE; Description Stick status message variable. See lastSuccess (
see page 93) for details.
7.2.1.2.1.7.3 lastSuccess Variable File CustomHTTPApp.c 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 (
Description see page 94) 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 91). 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 94)() function. 1. Replace (
see page 219) the initializer of the RAMStringTo[] array with the target email address.
2. Replace ( see page 219) 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 91) 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, 93
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
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 94) task function implements a four-state state machine. When the board is powered on, the state machine is initialized to the SM_HOME state, in which it waits for buttons 2 and 3 to be pressed. Once they are pressed, the task will enter the MAIL_BEGIN state. In the MAIL_BEGIN state, the task will attempt to requisition the SMTP module. Once it's able to do this, it will populate the SMTPClient ( see page 301) 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 302)) 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 93)
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 91) in CustomHTTPApp.c. Preconditions The SMTP client is initialized.
7.2.1.2.3 Generic TCP Client Functions Name GenericTCPClient ( page 95)
Description see
Implements a simple HTTP client (over TCP).
94
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
Variables Name
Description
RemoteURL ( ServerName ( ServerPort (
see page 96) Defines the URL to be requested by this HTTP client see page 96) Defines the server to be accessed for this application see page 96)
Note that if HTTPS is used, the ServerName ( change to an SSL enabled server.
see page 96) and URL must
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 149). This socket will use a TCP_PURPOSE_GENERIC_TCP_CLIENT socket type ( see page 149) from the TCP socket structure ( see page 150) 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 166) 125 bytes of data and then use an HTTP GET ( see page 230) 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 94)
Returns None
95
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
Description This function implements a simple HTTP client, which operates over TCP. The function is called periodically by the stack, and waits for BUTTON1 to be pressed. When the button is pressed, the application opens a TCP connection to an Internet search engine, performs a search for the word "Microchip" on "microchip.com", and prints the resulting HTML page to the UART. This example can be used as a model for many TCP and HTTP client applications. Preconditions TCP is initialized.
7.2.1.2.3.2 Variables Module Generic TCP Client (
see page 94)
Variables Name
Description
RemoteURL (
see page 96) Defines the URL to be requested by this HTTP client
ServerName (
see page 96) Defines the server to be accessed for this application
ServerPort (
see page 96)
Note that if HTTPS is used, the ServerName ( change to an SSL enabled server.
see page 96) and URL must
7.2.1.2.3.2.1 RemoteURL Variable File GenericTCPClient.c 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 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 C WORD ServerPort = HTTP_PORT; Description Note that if HTTPS is used, the ServerName (
see page 96) and URL must change to an SSL enabled server.
96
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
7.2.1.2.4 Generic TCP Server Functions Name
Description
GenericTCPServer ( page 98)
see
Implements a simple ToUpper TCP Server.
Macros Name SERVER_PORT ( page 98)
Description see
Defines which port the server will listen (
see page 172) on
Description Overview The Generic TCP Server example demonstrates how to build a TCP server application. Once you connect ( see page 168) 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 152) 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 98) 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 149). This socket will use a TCP_PURPOSE_GENERIC_TCP_SERVER socket type ( see page 149) from the TCP socket structure ( see page 150) that was initialized in your configuration files. It will also listen ( see page 172) on TCP port 9760 (defined by the macro SERVER_PORT ( see page 98)). 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 172) for new connections.
97
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 97)
Returns None Description This function implements a simple TCP server. The function is invoked periodically by the stack to listen ( see page 172) 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 Macros Name
Description
SERVER_PORT ( page 98)
see
Defines which port the server will listen (
see page 172) on
Module Generic TCP Server (
see page 97)
7.2.1.2.4.2.1 SERVER_PORT Macro File GenericTCPServer.c C #define SERVER_PORT 9760 Description Defines which port the server will listen (
see page 172) on
7.2.1.2.5 Ping (ICMP) Demo Functions Name PingDemo (
Description see page 99)
Demonstrates use of the ICMP (Ping) client.
Macros Name HOST_TO_PING ( page 100)
Description see
Address ( see page 144) 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. 98
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 99) 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 261) 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 ( action depending on the return value:
see page 263) callback function and take
Value Action -2
Remain in this state and keep waiting for a response.
-1
Write a message to the LCD indicating that the ping timed out. Change state to SM_HOME.
-3
Write a message to the LCD indicating that the DNS module couldn't resolve the target address. Change state to SM_HOME.
Other Convert the response time to a text string and print it to the LCD. Change state to SM_HOME.
7.2.1.2.5.1 PingDemo Function File MainDemo.h C void PingDemo(); Module Ping (ICMP) Demo (
see page 98)
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.
99
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
7.2.1.2.5.2 Macros Macros Name
Description
HOST_TO_PING ( page 100)
see
Address ( see page 144) 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 98)
7.2.1.2.5.2.1 HOST_TO_PING Macro File PingDemo.c 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 144) 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 ( 113)
Description see page Prepare, validate remote node which will receive trap and send trap pdu.
SNMPGetTimeStamp ( page 113)
see
Obtains the current Tick value for the SNMP time stamp.
Macros Name
Description
MAX_TRY_TO_SEND_TRAP ( see page 115) SNMP_MAX_NON_REC_ID_OID Update the Non record id OID value which is part of CustomSnmpDemo.c ( see page 115) file STACK_USE_SMIV2 ( page 115)
see
Default STACK_USE_SMIV2 is enabled . For Stack V5.31, STACK_USE_SMIV2 should be disabled.
Variables Name gSendTrapSMstate ( page 114)
Description see
This is variable gSendTrapSMstate.
gSnmpNonMibRecInfo ( see page 114)
OLD snmp.mib file with SMIv1 standard
gSnmpv3UserSecurityName ( see page 114)
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 100
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 :\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. You will require two firmware packages to run the SNMPv3 server demo. Each of these must be installed in the order listed, as some files will be overwritten. The software encryption library is not required if the SNMPv3 services are not intended.
1. The Microchip Application Libraries, including TCP/IP Stack v5.31 or later. This code is available at www.microchip.com/mal. 2. Microchip's Data Encryption Libraries. This demo uses the SSL security layer to communicate with Google. To use SSL with the TCP/IP stack, you will require these libraries. They are available in a CD-based or downloadable format from MicrochipDirect for a small fee (required to comply with U.S. cryptographic export restriction screening). You must execute the "Microchip TCPIP Stack vX.XX Encryption Add-on.exe" installer to install the files required by the demo. The ARCFOUR.c/h and RSA.c/h cryptographic files in this installer will replace the dummy versions found with the default TCP/IP Stack installation. To enable SNMPv3 functionality, you must add the PIC32_AES.a library from the Data Encryption Libraries to your demo project.
Note: For existing Microchip SNMP V1 and V2c users. • SNMP V1/V2c users wanting to upgrade the Microchip TCP/IP Stack from older versions to the latest version and continue to use SNMP V1/V2c can get the SNMP V1/V2c services from this agent, provided they do not modify the default settings of the SNMP module in v5.25 onward. • The implementation framework for V1 and V2c remains the same, except for a few new features and functions. The names and parameters of some of the functions have been changed. V1/V2c users may have to make changes to their application-specific code. There should not be any change in the SNMP stack code unless users have incorporated application code in the SNMP stack.
101
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
• 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 SNMP Server (Agent) (
see page 100)
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 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 SNMP Server (Agent) (
see page 100)
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. 102
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
Refer to AN870 - "SNMP V2c Agent for Microchip TCP/IP Stack" for more details on the MIB scripts, community names, and demo SNMP MIB variable tree structure. The following figure shows the variables implemented in the Microchip SNMP Agent.
The ASN.1 format mchip.mib file is defined with a private variable tree structure for the MIB variables. Also the mchp.mib is added with number of OIDs which could be accessed only with SNMPv3 request. The browser can access every variable in the MIB database provided the community name matches. The access to the MIB variables is restricted to the type of the request. The RFC1213 mib variables could be accessed with SNMPv2c/v3 request. But the SNMP-FRAMEWORK-MIB.mib variables could only be accessed with SNMPv3 reqeust if the credentials are matched and the message is authenticated. To modify these MIB variables, corresponding changes must be made to both MIB scripts (snmp.mib and mchip.mib). The following figure shows the Microchip private MIB variable tree structure in the browser.
Configuring the Browser To configure the iReasoning MIB browser: 1. Select the "Advanced" tab in the browser.
The following configuration window will be displayed:
103
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
2. If V2C services are required, select SNMP version V2c, configure the Read and Write community to the browser. • The V2c agent will respond only to the queries from SNMP MIB browsers using the same community. That is, the V2c agent and the browser should be members of the same community. • If the community fields are left blank, the manager sends the SNMP request with the community name as "public." • The V2c agent is configured by default with 3 Read communities ("public", "read", "") and 3 Write communities ("private","write","public"). • The default maximum community length is 8 characters. • As the default communities also contain the "public" community name, the agent will respond to all of the browsers requesting the "public" community. • The TCP/IP Configuration Wizard ( see page 59) can be used to configure the default SNMP community names. At run time, the community names can be dynamically configured using the HTTP interface for SNMP community name configuration. If the V2c agent receives an SNMP request with an unknown community name, the agent will generate an Authentication ( see page 86) 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.
104
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
USER 1
USER 2
USER 3
USM User
microchip
SnmpAdmin
root
Security Level
auth, priv
auth, no priv
no auth, priv
Auth Algorithm
MD5
SHA1
Auth password
auth12345
ChandlerUS
Privacy Algorithm
AES
Privacy password
priv12345
no
5. The Microchip SNMPv3 stack does support only one Context Engine ID with the server. Leave the "Context Name" option in the "Advanced" tab empty. It is ignored on the server. 6. According to the user and the auth and privacy protocols configured with the SNMP browser, the UDP authenticated and encrypted message would be exchanged between server and the client. • If the USER 1 values, as in above table, are configured in the MIB browser, the data exchange between client and server is encrypted and authenticated. The PDU could be captured in the Ethernet packet sniffer like WireShark and examined. As the data is encrypted and authenticated, the data integrity and the privacy is achieved. • If USER 2 values, as in above table, are configured in the MIB browser, the data exchange between client and server is authenticated. The data integrity would be checked once the data is received at either end. The message authentication mechanism protects from the possible data sniffing and modification threat, and alos guarantees that the data is received from the authenticated and guaranteed source. • if USER3 values, as in above table, are configured in the MIB browser, the data exchange between client and server is neither authenticated nor encrypted. • Considering the above three USER configurations, if the SNMP server is to be accessed over WAN, in the internet cloud, tha data should be encrypted and authenticated to have the highest level of data privacy and integrity. 7. Configure the IP address of the SNMP agent to the "Address (
see page 144) 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 105
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
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 SNMP Server (Agent) (
see page 100)
Description Get 1. Select the "Advanced" tab and configure the SNMP version to '1' and the Read community to "public". 2. Select "Get" from the operations menu. 3. Select the sysDescr variable from the MIB Tree. The Result Table displays the sysDescr variable information. Repeat this procedure for any MIB variable. For SNMP V2c, repeat the same procedure, substituting '2' in place of '1' in the version configuration.
As explained earlier, the V2c agent is configured with three Read and Write community defaults. Configure the browser to use any of these communities and try accessing the MIB variables. You should be able to access some of the MIB variables even with the Read Community configured as any of the 'write' community defaults. For GET operations, if the Read or Write community matches, the agent processes the request. For SET operations, the received community names must match any of the 'write' community names. For SNMP V3, substitute '3' in place of '1' in the version configuration in the "Advanced" tab. Configure the other user based auth and priv credentials as explained in the "MIB Browsers" section. With appropriate credentials, all the MIB variables are accessible. Select any of the MIB variables in the MIB tree and do a GET operation.
Get_Next 1. Repeat the process for GET. Select the sysDescr variable from the MIB tree. Select "Get Next" from the operations menu. The result table will display the sysObjectID variable information. 2. Repeat for additional MIB variables to get the information for the corresponding next variable.
106
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
3. Set the SNMP MIB Browser version to v1/v2c. Try to access the private MIB variable "snmpv3PvtObject" with OID value as 43.6.1.4.1.17095.6.1. The access should be restricted. Set the verison to V3, configre the credentails, again try a Get_Next operation for the sae variable. The access should be granted. Get_Bulk This operation is supported in SNMP V2c and SNMP V3. Get_Bulk enables the collection of bulk information from the agent with a single request from the manager. 1. Configure the SNMP version to '2' or '3' in the SNMP browser. 2. If version is configured to '2', set the Read Community to 'public' or 'read.' 3. If version is configured to '3', configure the appropriate V3 credentials. 4. Select the sysDescr variable from the MIB tree. 5. Select the Get Bulk operation from the Operations menu. The result table will display information for 10 MIB variables in a single request (if the Max-Repetitions=10 and Non-Repeaters=0 is configured). These variables are the lexicographical successors of the sysDescr variable. The number of variables that the agent will respond with can be configured in the browser through the menus: "Tools->Options->Non-Repeaters" and "Tools->Options->Max-Repetitions." The Non-Repeaters and Max-Repetitions numbers are extracted by the SNMP agent from the received Get_Bulk request and the number of variables that will be included in the response PDU is calculated. for more information on calculating the number of variables, Non-Repeaters, and Max-Repetitions, refer to RFC 3416.
Set The Set command updates the variable information of the MIB database in the agent. The Set command can be performed only on those variables which are declared as 'READWRITE' in the MIB scripts, and only if the community name matches any one of the 'write' community names configured with the agent. 1. Select the ledD5 variable from the MIB tree. 2. Configure the SNMP version to '1' or '2.' Configure the Write Community to 'public', 'write', or 'private'. 3. If version is configured to '3', configure the appropriate V3 credentials. 4. Select 'Set' from the Operations menu.
The SNMP SET window will pop up. Enter the value for the browser in the OID field.
107
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
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 SNMP Server (Agent) (
see page 100)
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: SNMPv1 TRAP v1 (Enabled by default)
• Comment out the #define SNMP_TRAP_DISABLED macro
SNMPv2c • Comment out the #define SNMP_TRAP_DISABLED macro
SNMPv3 • Comment out the #define SNMP_TRAP_DISABLED macro • Uncomment the #define SNMP_V1_V2_TRAP_WITH_SNMPV3 macro
108
7.2 Available Demos
TRAP v2 (Not supported) (Disabled by default)
Microchip TCP/IP Stack Help
• Comment out the #define SNMP_TRAP_DISABLED macro • Uncomment the #define SNMP_STACK_USE_V2_TRAP macro
Demo App
• 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 'trapReceiverIPAddress.' • If Button 3 on the demo board is pressed, an organization-specific PUSH_BUTTON trap will be sent. The current implementation of the V2c agent also generates a standard "Authentication (
see page 86) Failure Trap":
• If a request is received to modify (Set) a private MIB variable, or • If the value of the variable is requested (get) by a browser with the wrong community name. Procedure: 1. Open the "Advanced" configuration menu, configure the SNMP version to '2,' and configure the Write Community to "public', 'write', or 'private'. 2. Select the 'trapEnabled.0' variable from the MIB tree. 3. Select 'Set' from the Operations menu. 4. Enter '1' in the value field of the SNMP SET window. 5. Select 'trapReceiverIPAddress.0' from the MIB tree. 6. Set the value to the IP address of the PC on which the SNMP browser is installed and running. 7. Select 'trapCommunity.0' from the MIB tree. 8. Set the community name of the SNMP browser (the default community, if not set, is 'public'). The 'trapCommunity' name will work as a filter for the SNMP browsers on a trap-monitoring server. 9. Open the "Trap Receiver' utility that was installed with the iReasoning MIB browser (Start->Programs->iReasoning->MIB Browser->Trap Receiver).
109
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
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 86) Failure trap, configure the Read Community in your browser to a community name that is not supported by the agent (the default supported names are 'public' and 'read'). For example: 1. Configure 'mchp' as the Read Community name in the browser. 2. Select the private MIB variable LED5 from the MIB tree and issue a 'Get' operation from the browser. The result table of the browser won't display any result, but the Trap Receiver will receive and Authentication ( 86) Failure trap.
see page
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: 110
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
• Uncomment #define SNMP_TRAP_DISABLED • Uncomment #define SNMP_STACK_USE_V2_TRAP The SNMP V2 Trap PDU structure is: Version (2) | community | SNMP-PDU pdu-type (TRAP=0xA7) | request-id | error-status | err-index | varbind List The first two variable varbinds in the variable binding list of an SNMPv2-TRAP-PDU are sysUpTime.0 and snmpTrapOID.0, respectively. If any additional variables are to be included, then each of these varbind structures must be copied to the variable binding list. For the SNMPv2 multiple TRAP variable varbind demonstration, ANALOG_POT0 is used to generate an event and transmit an SNMP v2 Trap PDU. Adjust the analog potentiometer to a value greater than 512 (turn it clockwise) on the demo board. In addition to the sysUpTime.0 and snmpTrapOID.0 varbinds, the additional varbinds that are included with the trap PDU are: • PUSH-BUTTON • LED0_IO • ANALOG_POT0 The following figure shows a V2 formatted trap with ANALOG_POT0 as the variable binding to be notified.
The next figure shows a multiple-variable varbind for an SNMP V2 Trap PDU, with the three additional variable bindings:
111
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
7.2.1.2.6.5 HTTP Configuration Module SNMP Server (Agent) (
see page 100)
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.
112
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
7.2.1.2.6.6 Functions Functions Name
Description
SendNotification ( 113)
see page Prepare, validate remote node which will receive trap and send trap pdu.
SNMPGetTimeStamp ( page 113)
see
Obtains the current Tick value for the SNMP time stamp.
Module SNMP Server (Agent) (
see page 100)
7.2.1.2.6.6.1 SendNotification Function File CustomSNMPApp.c C static BOOL SendNotification( BYTE receiverIndex, SNMP_ID var, SNMP_VAL val, UINT8 targetIndex ); Description This routine prepares the trap notification pdu, sends ARP and get remote device MAC address to which notification to sent, sends the notification. Notofication state machine is getting updated if there is any ARP resolution failure for a perticular trap destination address. Remarks None. Preconditions SNMPTrapDemo() is called. Parameters Parameters
Description
receiverIndex
The index to array where remote ip address is stored.
var
SNMP var ID that is to be used in notification
val
Value of var. Only value of BYTE, WORD or DWORD can be sent.
targetIndex
snmpv3 target index
Return Values Return Values
Description
TRUE
If notification send is successful.
FALSE
If send notification failed.
7.2.1.2.6.6.2 SNMPGetTimeStamp Function File CustomSNMPApp.c C static DWORD SNMPGetTimeStamp();
113
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
Description This function retrieves the absolute time measurements for SNMP time stamp.Use TickGet ( TickGetDiv64K ( see page 517) to collect all 48bits of the internal Tick Timer.
C BYTE gSnmpv3UserSecurityName[USER_SECURITY_NAME_LEN]; Description This is variable gSnmpv3UserSecurityName.
7.2.1.2.6.8 Macros Macros Name
Description
MAX_TRY_TO_SEND_TRAP ( see page 115) SNMP_MAX_NON_REC_ID_OID Update the Non record id OID value which is part of CustomSnmpDemo.c ( see page 115) file STACK_USE_SMIV2 ( page 115)
see
Default STACK_USE_SMIV2 is enabled . For Stack V5.31, STACK_USE_SMIV2 should be disabled.
Module SNMP Server (Agent) (
see page 100)
7.2.1.2.6.8.1 MAX_TRY_TO_SEND_TRAP Macro File CustomSNMPApp.c 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
7.2.1.2.6.8.2 SNMP_MAX_NON_REC_ID_OID Macro File CustomSNMPApp.c 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 C #define STACK_USE_SMIV2 Description Default STACK_USE_SMIV2 is enabled . For Stack V5.31, STACK_USE_SMIV2 should be disabled. 115
7.2 Available Demos
Microchip TCP/IP Stack Help
Demo App
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 addresses and host names of all devices with the Announce ( see page 152) Protocol enabled on your network. You may have to configure your computer's firewall to prevent it from blocking UDP port 30303 for this solution. 3. If your board is connected directly with your computer with a crossover cable: 1. Open a command/DOS prompt and type 'ipconfig'. Find the network adaptor that is connected to the board. The IP address of the board is located in the 'Default Gateway' field 2. Open up the network status for the network adaptor that connects the two devices. This can be done by right clicking on the network connection icon in the network settings folder and select 'status' from the menu. Find the 'Default Gateway' field. 5. Open a command/DOS prompt. Type "telnet ip_address 9761" where ip_address is the IP address that you got from step 4.
6. As you type characters in the command prompt, they will be transmitted over the Telnet ( see page 485) TCP port to the PIC, and then transmitted out of the PIC's UART to appear on your terminal program. As you type characters in the terminal program, they will be transmitted to the PIC through the UART module, and then retransmitted over the TCP connection to appear in the command prompt Telnet ( see page 485) 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: 116
7.2 Available Demos
Microchip TCP/IP Stack Help
Internet Bootloader
• STACK_USE_ZEROCONF_LINK_LOCAL • STACK_USE_ZEROCONF_MDNS_SD Currently, the use of Zeroconf is limited to the WiFi demo applications (and the MRF24WB0M module). Future versions of the stack should enable Zeroconf support across all Ethernet solutions. Link Local The first component of Zeroconf is the ability to self-assign an IP address to each member of a network. Normally, a DHCP server would handle such situations. However, in cases where no DHCP server exists, Zeroconf enabled devices negotiate unique IP addresses amongst themselves. mDNS The second component of Zeroconf is the ability to self-assign human-readable hostnames for themselves. Multicast DNS provides a local network the ability to have the features of a DNS server. Users can use easily remembered hostnames to accesses the devices on the network. In the event that devices elect to use the same hostname, as in the IP address resolution, each of the devices will auto-negotiate new names for themselves (usually by appending a number to the end of the name). Service Discovery The last component of Zeroconf is service discovery. All Zeroconf devices can broadcast what services they provide. For instance, a printer can broadcast that it has printing services available. A thermostat can broadcast that it has an HVAC control service. Other interested parties on the network who are looking for certain services can then see a list of devices that have the capability of providing the service, and connect ( see page 168) 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 168) to it. Demo The demo, when enabled, shows all three items above working together. Each development kit in the network assumes the hostname of MCHPBOARD-x.local, where x is an incrementing number from 1 (only in the case where multiple kits are programmed for the network). Each board will broadcast it's service, which is the DemoWebServer. Zeroconf Enabled Environments All Apple products have Zeroconf enabled by default. On Windows, you'll need to download the Safari web browser, and during the install, enable support for Bonjour. Note that in the Safari browser, you can browse and see a list of all Bonjour enabled devices, and click through to them automatically.
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
117
7.2 Available Demos
Microchip TCP/IP Stack Help
Internet Bootloader
• 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 bit and then execute a RESET instruction. When the bootloader returns control to the main application, the NOT_POR bit will be in the set state. If an application needs to reset quickly without waiting for the bootloader timeout, it should leave this bit in the set state. This will cause the bootloader to skip its normal operation and return immediately to the application. Prior to executing the RESET instruction to reenter the bootloader, the main application can specify the MAC and IP address for the bootloader to use. To do this: 1. Select a random memory location where 12 bytes can be written 2. Copy the MAC address to the chosen memory location at offset 0 3. Copy the IP address to the chosen memory location at offset 6 4. Compute an IP checksum of the MAC and IP address stored at the memory locations 0 through 9 5. Write the IP checksum at the chosen memory location at offset 10 6. Store the address of the chosen memory location into the PRODH:PRODL registers 7. Clear the RCON bit and execute a RESET instruction to enter the bootloader Upon entry, the bootloader will detect that the RCON 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 314) module which can perform the above procedure upon detection of a TFTP packet. When the Reboot ( see page 314) 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.
118
7.2 Available Demos
Microchip TCP/IP Stack Help
Internet Bootloader
Memory Map The entire program memory map when using the bootloader is shown below.
*: GOTO instruction is automatically generated by bootloader when writing. Application instruction at address 000000h is moved to Bootloader Jump Table. **: Some configuration options are not supported and will automatically be changed by the bootloader before flashing. The bootloader requires HS or HS+PLL oscillator mode and does not support 1:1 and 1:2 Watchdog Timer Postscale modes. Switching between Extended and non-Extended mode is not supported either. (The bootloader must be recompiled to change modes.) The bootloader uses a block of 8256 bytes of program memory. To prevent the application from inadvertently using this block, you should modify the linker script in your application prior to compiling. For example, for the MPLAB® C18 C compiler, the linker script will contain a CODEPAGE line describing the available Flash memory in the device. For the PIC18F97J60 product with 128kB of program memory, the linker script (18f97j60i.lkr) will contain a line such as: CODEPAGE NAME=page START=0x2A END=0x1FFF7 This line indicates that the linker can place application constants and code anywhere between 00002Ah and 01FFF7h. This line must be split into two CODEPAGE lines to describe the gap in available program memory occupied by the bootloader. Ex: CODEPAGE NAME=page START=0x2A END=0x1DBBF CODEPAGE NAME=page2 START=0x1FC00 END=0x1FFF7 The above example removes the Jump Table and Bootloader Code blocks for the PIC18F97J60 with 128kB of Flash memory. Other devices with less Flash memory will need to use different start and end values according to the Jump Table start address and Bootloader Code end address described in the memory map figure above. 119
7.2 Available Demos
Microchip TCP/IP Stack Help
Internet Bootloader
Erase Operations The TFTP server performs a "bulk erase" before starting any TFTP put (write) operation. The erase is not a true bulk erase because the bootloader and configuration words remain intact. However, all other locations are reverted to their unprogrammed state. The erase procedure starts with the Flash page containing the Jump Table and continues backwards in memory towards address 000000h. After address 000000h is erased, the last program memory page containing the device configuration words is erased. For example, assuming a PIC18F97J60 with 128kB of Flash, the erase procedure will follow these steps: 1. Erase 01D800h-01DBFFh 2. Erase 01D400h-01D7FFh 3. Erase 01D000h-01D3FFh 4. ... 5. Erase 000400h-0007FFh 6. Erase 000000h-0003FFh 7. Erase 01FC00h-01FFFFh After the last page containing the configuration words are erased, the configuration words are immediately reprogrammed to their previous value. This algorithm provides very robust operation with an extremely low likelihood of destroying access to the bootloader due to an unexpected event (ex: power or network connectivity is lost while bootloading). Unexpected events will leave the first GOTO instruction at address 000000h intact, ensuring that the bootloader will start up again. Because the configuration words are erased last, there will not be any means of circumventing the internal code protect feature while application code still remains in the device. Program Operations Program operations are performed sequentially starting at address 000000h and growing upwards, as presented in the .hex file to be programmed. The device configuration words are typically the last values encountered in the .hex file. Because the erase procedure involves clearing the configuration words and then immediately reprogramming them, the configuration words will already be programmed by the time the configuration words are encountered in the .hex file. Therefore, if the .hex file contains different configuration words from what are already stored in the Flash memory, the bootloader will have to perform a new erase operation on the last page prior to programming the new configuration words. This extra erase/write cycle will reduce overall Flash endurance on the last page as compared to the rest of the device. However, the bootloader will not perform this erase/write if the configuration words have not changed. This feature preserves endurance for most application firmware upgrades, which typically do not require different configuration options to be programmed. Read Operations To save code space, the bootloader currently only supports reading through the TFTP server as binary data. Instead of getting a .hex file from a TFTP get operation, the bootloader will send back a binary file sized to the amount of internal Flash memory available (128kB for PIC18F97J60, 64kB for PIC18F66J60, etc.). The bootloader verifies code immediately after programming devices, so the read feature is primarily for debugging only. Read operations are disabled if the currently programmed application has the PIC® microcontroller Code Protect feature turned on.
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 144): 192.168.97.60
• MAC Address (
see page 144): 00-04-A3-00-00-00
120
7.2 Available Demos
Microchip TCP/IP Stack Help
Internet Bootloader
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 314) module, then the bootloader will use the application assigned IP and MAC addresses (if provided). The only services that are available during bootloader operation are TFTP and ARP. ICMP (ping) and other services are not implemented. Configuring Your PC (Power-on Reset entry) To access the bootloader, the bootloader's IP address must be on the same subnet as your computer. For the default 192.168.97.60 IP address, you must temporarily change the settings on your PC. If the bootloader's IP address was application specified and already on the same subnet as your PC, then this section should be skipped. The following instructions assume you are using Microsoft® Windows® XP and will vary for other operating systems.
1. Open Network Connections. 2. Right click on the network adapter that you are using to communicate with the bootloader and choose Properties.
3. Select Internet Protocol (TCP/IP) and click Properties. 121
7.2 Available Demos
Microchip TCP/IP Stack Help
Internet Bootloader
4. Select Use the following IP address and then enter the IP address 192.168.97.61.
5. Click OK and then Close on the previous dialog to close them and set the new address. TFTP Operation (Power-on Reset entry) Most operating systems come with a TFTP client built in. In Microsoft Windows, this utility is named tftp.exe. This utility is a very simple console application which can be used to upload your application .hex file over the network to the bootloader. To perform a Flash upgrade using the tftp.exe client, follow these procedures: 1. At a console, type the following command, but do not execute it. Make appropriate path changes to the .hex file. tftp 192.168.97.60 put "C:\Microchip Solutions\TCPIP Demo App\TCPIP Demo App-C18.hex" 2. Power cycle the target board or if the device has a MCLR reset button, press it. 3. Quickly press enter to execute the tftp command. If firmware is already in the device, the bootloader will automatically terminate after approximately 4 seconds, so you must execute the tftp command within the 4 second window. 4. If successful, the TFTP client will indicate how long the transfer took. Actual programming time will vary based on numerous factors, including need to erase the Flash first, .hex file size, .hex file complexity, and internal programming time. The reported transfer rate is therefore not a good metric of network performance in embedded applications.
The bootloader does data read back verification shortly after writing and does not need a second step to read back the Flash contents. If a verification error occurs, the error will be immediately reported to the TFTP client.
The most likely cause of a verification failure is not a Flash endurance problem, but rather, an invalid .hex file given as input. As shown in the bootloader memory map, .hex files cannot contain any data within the 8KB area of Flash were the bootloader is stored. The bootloader internally masks off this region of Flash and treats it as read only to prevent bootloader corruption. As a result, if the .hex file contains data in the read-only region, the write will fail and verification will show a mismatch. 5. After a successful write, the bootloader will time out after approximately 4 seconds and begin executing the main application that was just loaded. After completing the TFTP upload process, restore your PC's IP address settings to allow normal network activity and access to the application you bootloaded. TFTP Operation (Application entry)
122
7.2 Available Demos
Microchip TCP/IP Stack Help
Internet Radio
If using an application which auto-detects TFTP packets and enters the bootloader as needed, such as the Reboot ( see page 314) 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)
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 168) 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 168) 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.
123
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. 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.
7.2.5.1 Standalone Commands These CLI commands are not related to the wireless or networking interface directly.
help Lists all the available CLI commands for the MRF24WB0M. getwfver Lists the WiFi firmware and host driver version numbers.
124
7.2 Available Demos
Microchip TCP/IP Stack Help
WiFi Console
reset Issues a host reset. cls Resets the prompt. kill iperf Kills a running iperf session. See the section on iperf (
see page 128) for more information.
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: iwconfig [ [ [ [ [ [ [ [ [ [
Note: iwconfig with no options will display wireless status. ssid name
1-32 ASCII characters. Currently doesn't accept (
see page 166) spaces in the SSID name.
mode idle
Forces the MRF24WB0M to disconnect from any currently connected network (adhoc or infrastructure).
managed
The MRF24WB0M will connect ( see page 168) to the SSID in infrastructure mode. Note that all the network parameters must be correct before this command is called.
adhoc
The MRF24WB0M will connect ( see page 168) to the SSID in adhoc mode. Note that all the network parameters must be correct before this command is called.
channel channel list
A comma separated list of all the channels to scan.
all
Sets the MRF24WB0M to scan all channels in the given regulatory domain.
power reenable
Enables all power saving features (PS_POLL) of the MRF24WB0M.
disable
Disables any power savings features. The MRF24WB0M will always be in an active power state. 125
7.2 Available Demos
Microchip TCP/IP Stack Help
WiFi Console
unicast
The MRF24WB0M will be in it's deepest sleep state, only waking up at periodic intervals to check for unicast data. The MRF24WB0M will not wake up on the DTIM period for broadcast or multicast traffic.
all
The MRF24WB0M will wake up to check for all types of traffic (unicast, multicast, and broadcast).
domain fcc
United States channels 1-11.
ic
Canada channels 1-11.
etsi
European channels 1-13.
spain
Spanish channels 10-11.
france
French channels 10-13.
japana
Japanese channel 14.
japanb
Japanese channels 1-11.
rts length
Set the requested number of bytes to send. Default max is 2347.
txrate 0
The MRF24WB0M will do automatic rate adaptation between 1 and 2 Mbps.
1
Sets the MRF24WB0M to fixed data rate of 1Mbps.
2
Sets the MRF24WB0M to fixed data rate of 2Mbps.
scan Instructs the MRF24WB0M to perform an active site scan. Scan results will be displayed to the output terminal. hibernate Removes power to the MRF24WB0M. wakeup Restores power to the MRF24WB0M and reconnects. Note: scan is only supported by the WiFi EZConfig demo.
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 [ [ [ [ [
] ] netmask ] gateway ] auto-dhcp ]
Note ifconfig by itself will give network status. 126
7.2 Available Demos
Microchip TCP/IP Stack Help
WiFi Console
IP address Use a static IP address. IP address must be in dot-decimal notation. Note that this command will return an invalid parameter if the DHCP client is enabled. First disable the DHCP attempts (ifconfig auto-dhcp drop) before running this command. MAC address Redefine the device MAC address. MAC address must be specified in hexadecimal colon notation. This command can only be issued when the MRF24WB0M is in idle mode. Doing so at other times can have unexpected results. netmask IP address
Use the specified IP address for the netmask. The netmask value is specified in dot-decimal notation.
gateway IP address
Configure the gateway address. The gateway value is specified in dot-decimal notation.
auto-dhcp start
Starts the DHCP client. Only valid if the DHCP module has been compiled in. DHCP client is started by default.
drop
Stops the DHCP client. A static IP address will need to be assigned to the device. Only valid if the DHCP module has been compiled in.
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 ] [ key ] [ psk ] [ phrase ] Note iwpriv by itself will display network security settings. enc none
The MRF24WB0M will not use any encryption to connect ( network.
see page 168) to the specified
wep
The MRF24WB0M will use either WEP-40 (short) or WEP-104 (long) encryption to connect ( page 168) to the specified network.
wpa-psk
The MRF24WB0M will use the specified 32-byte PSK to connect ( WPA/WPA2 network.
see
see page 168) to the
127
7.2 Available Demos
wpa-phrase
Microchip TCP/IP Stack Help
WiFi Console
The MRF24WB0M will take the given 1-32 ASCII character passphrase, along with the SSID, and compute the required 32-byte PSK for the network. Note that doing so takes approximately 30 seconds to complete the calculation.
key [1] [2] [3] [4]
Instructs the MRF24WB0M to use this key for connecting to the WEP encrypted network. Note that only key 1 is considered safe to use among different AP vendors. Keys 2-4 can have implementation specific entries that may not be compatible from AP to AP.
value
If value is specified, this will instruct the MRF24WB0M to use the specified key number and also program the device with this key value. For WEP-40 networks, this implies the key is either 5 ASCII characters of 10 hex characters in length. For WEP-104 networks, this implies the key is either 13 ASCII characters or 26 hex characters in length. The console only accepts hex WEP keys. Therefore, the user must do the ASCII to hex conversion for their ASCII keys.
psk value
32-byte hex value for the PSK. This value can be calculated from the following website hosted on the 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 ] [ -u ] [ -i ] [ -b ] [ -t
![[PDF] Download Pro MERN Stack: Full Stack Web App Development ...](https://m.moam.info/img/260x300/pdf-download-pro-mern-stack-full-stack-web-app-dev_647799ae097c474e708be226.jpg)
![[PDF] Download Pro MERN Stack: Full Stack Web App Development ...](https://m.moam.info/img/260x300/pdf-download-pro-mern-stack-full-stack-web-app-dev_6477a6d1097c474d228c471b.jpg)
![[PDF] Download Pro MERN Stack: Full Stack Web App Development ...](https://m.moam.info/img/260x300/pdf-download-pro-mern-stack-full-stack-web-app-dev_6477b6b7097c4744708c04f7.jpg)
![[PDF] Download Pro MERN Stack: Full Stack Web App Development ...](https://m.moam.info/img/260x300/pdf-download-pro-mern-stack-full-stack-web-app-dev_6477b6b8097c4796708c01e3.jpg)
![[PDF] Download Pro MERN Stack: Full Stack Web App Development ...](https://m.moam.info/img/260x300/pdf-download-pro-mern-stack-full-stack-web-app-dev_6477da85097c47a9708c2d05.jpg)
![[PDF] Download Pro MERN Stack: Full Stack Web App Development ...](https://m.moam.info/img/260x300/pdf-download-pro-mern-stack-full-stack-web-app-dev_6477e9c2097c474d228c91a1.jpg)
![[PDF] Download Pro MERN Stack: Full Stack Web App Development ...](https://m.moam.info/img/260x300/pdf-download-pro-mern-stack-full-stack-web-app-dev_64788bef097c4796708cee21.jpg)
![Download [PDF] Pro MERN Stack: Full Stack Web App Development ...](https://m.moam.info/img/260x300/download-pdf-pro-mern-stack-full-stack-web-app-dev_6477fc24097c474d228ca5e5.jpg)
![[PDF] Download Pro MERN Stack: Full Stack Web App Development ...](https://m.moam.info/img/260x300/pdf-download-pro-mern-stack-full-stack-web-app-dev_6477fdb7097c4786708c530a.jpg)
![[PDF] Pro MERN Stack: Full Stack Web App ... - Google Sites](https://m.moam.info/img/260x300/pdf-pro-mern-stack-full-stack-web-app-google-sites_6477173d097c474b228bad7b.jpg)
![([PDF]) Pro MERN Stack: Full Stack Web App ... - Google Sites](https://m.moam.info/img/260x300/pdf-pro-mern-stack-full-stack-web-app-google-sites_647847dd097c474b228d04cd.jpg)
