Understanding PIC WEB boards and how to use Microchip's TCP-IP Stack

Re !B" #anuar$ %&'( Cop$right)c* %&'%" +,IME- ,td" .// rights reser ed

I0TR+1UCTI+02
The PIC-WEB family of boards are development boards based on Microchip open source TCP-IP stack. t the moment this paper is !ritten the family includes these boards"

PIC-MICR+-WEB
With PIC#$%&'(&) microcontroller !ith inte*rated Ethernet+ ,- M./ operation+ #-$0bytes %lash+ 1.$ 0bytes 2am+ T,34B)## data flash for stora*e #-$0bytes space.

PIC-MI0I-WEB
With PIC#$%-3(#) microcontroller and E5C-$(&) Ethernet controller+ ,) M./ operation+ 1-0bytes %lash+ # 0Byte 2am+ T,34B)## dataflash for stora*e 6 #-$0Bytes space.

PIC-WEB
With PIC#$%&'(&) microcontroller and E5C-$(&) Ethernet controller+ ,) M./ operation+ 1-0bytes %lash+ 1.$ 0Bytes 2am+ T,34B)## dataflash for stora*e 6 #-$0Bytes space.

PIC-M.-I-WEB
With PIC#$%7'(&) !ith inte*rated Ethernet controller+ ,- M./ operation+ #-$0bytes %lash+ 1.$ 0Byte 2am+ T,34B)## dataflash for stora*e 6 #-$0Bytes space.

PIC-P34#3&
With PIC#$%&'(&) !ith inte*rated Ethernet controller+ ,- M./ operation+ #-$0bytes %lash+ 1.$ 0Byte 2am+ T,34B)## dataflash for stora*e 6 #-$0Bytes space.

PIC-5SM
With PIC#$%7'(&) !ith inte*rated Ethernet controller+ ,- M./ operation+ #-$0bytes %lash+ 1.$ 0Byte 2am+ internal flash used for stora*e

S+6TW.RE RU00I05 +0 T7ESE B+.R1S2

ll the boards use a modified version of the current Microchip TCP8IP stack 9ver. ,.#$ as of the moment of !ritin*: !hich is available for do!nload from the !eb pa*es of the boards at https"88!!!.olime;.com8 The only e;ception are the PIC-WEB and PIC-MI5I-WEB !hich use an older rev. 1.'& based soft!are+ a*ain available for do!nload from link on their !eb pa*es. To compile the sources and pro*ram the boards you !ill need"

MP< B I4E 6 available for free do!nload from http"88!!!.microchip.com8 Microchip MCC for PIC#$ 6 an evaluation version is also available MP< B-compatilble pro*rammer8debu**er 6 for e;ample our PIC-0IT1 or compatible 9you mi*ht need our PIC-IC=P adapter:. To may use the boards you !ill also need" n unused connection to your < 5 suitable po!er supply serial cable 9for PIC-WEB+ PIC-M >I-WEB+ PIC-P&'(&) and PIC-?=M: terminal pro*ram confi*ured at #7-)) bps+ $5# and no flo! control

1E6.U, B+.R1S C+06I5UR.TI+0 PIC-M.-I-WEB2

IP ddress" #7-.#&$.).73 6 4.CP E5 B<E4 by default@ the actual address used !ill be displayed on the <C4 and on the serial port M C address" ))"),"a1"))"))")3 ftp username" ftp pass!ord" olime;

PIC-MICR+-WEB2
IP ddress" #7-.#&$.).7$ 6 4.CP 4I= B<E4 by default M C address" ))"),"a1"))"))")a ftp username" ftp pass!ord" olime;

PIC-P34#3&2
IP ddress" #7-.#&$.).#)# 6 4.CP E5 B<E4 by default@ the actual address used !ill be displayed on the serial port M C address" ))"),"a1"))"))")b ftp username" ftp pass!ord" olime;

PIC-5SM2
IP ddress" #7-.#&$.).#)3 6 4.CP 4I= B<E4 by default. M C address" ))"),"a1"))"))")c ftp username" 5 pass!ord" 5

PIC-WEB" PIC-MI0I-WEB2
IP ddress" #7-.#&$.).1) 6 4.CP 4I= B<E4 by default. M C address" ))"),"a1"))"))")) ftp username" ftp pass!ord" microchip 5ote that ne!er versions of the stack mi*ht possibly have the ne! ftp username and pass!ord complyin* !ith the MicrochipAs ori*inal. Try !ith username" admin pass!ord" microchip

Progra88ing the preco8pi/ed he9-:i/es to the board

If you !ish to restore the factory default soft!are+ the respective .he; files are supplied in the BprecompiledC directory in the source archive. To pro*ram them to the board"

=tart MP< B and select the appropriate processor type from BConfigure->Select DeviceC Import the respective .he; file 9BFile->ImportC: Connect the board to your pro*rammer and apply po!er =elect the correct pro*rammer in MP< B 9BProgrammer->Select ToolC: Pro*ram the device 9BProgrammer->ProgramC:

In oking the 8enu on the seria/ port

The boards that have a serial port can display a confi*uration menu that can be used to chan*e the various confi*uration options of the board. By default this menu is not displayed and the user must follo! a special procedure described belo!" #.Connect the board to a serial port on your computer and start a terminal pro*ram at that port+ confi*ured for #7-))bps+ $5# data format -.Press and hold the Button on the board 9Button # on the PIC-M >IWEB:. 1.Press and release the 2eset button ,.2elease the Button. If you continue to hold it for , seconds after you have released the reset button+ the contents of the on-board dataflash !ill be completely erased and you !ill have to restore them. If you have follo!ed the procedure correctly+ a menu should be displayed on the serial port.

Changing the board settings )IP ; M.C addresses" etc!*

lmost every settin* of the boards can be chan*ed. There are various !ays to do that"

Dn the PIC-WEB+ PIC-M >I-WEB and PIC-P&'(&) you can enter the ne! settin*s throu*h the menu on the serial port 9see above: Dn the PIC-M >I-WEB+ PIC-MIC2D-WEB and PIC-P&'(&) you can use the BConfi*urationC !ebpa*e and chan*e the settin*s from the available !eb interface Dn the PIC-MI5I-WEB and the PIC-?=M you need to recompile the source code and repro*ram the boards. This is needed because the PIC-?=M does not have an e;ternal memory and the settin*s are stored directly in the pro*ram memory+ !hich cannot be chan*ed by itself. Dn the PIC-MI5I-WEB a serial port is not available and there are no enou*h resources available to implement a !eb-based confi*uration interface.

Up/oading web pages to the board!

The html pa*es that are displayed to the user are independent from the rest of the pro*ram and are stored in the dataflash memory on the board in all cases e;cept on the PIC-?=M board+ !here they are embedded in the rest of the pro*ram. =o in most cases the user also needs to upload a ne! !ebpa*e ima*e. This ima*e is *enerated by the MP%=-.e;e utility available in the BMicrochip\TCPIP Stack\Utilities C directory. The user should supply an input directory containin* the pa*es 9e.*. BTCPIP Demo pp\!e"Pages#lime$Ma$iC for PIC-M >I-WEB: and set the options 6 the output file format and the MP%= type. %or the different boards these settin*s are as follo!s" PIC-WEB, PIC-MINI-WEB" Dutput" Bin Ima*e@ MP%= Classic dvanced-EDutput %ormat"

PIC-MICRO-WEB, PIC-MAXI-WEB, PIC-P67J60" Dutput" Bin Ima*e@ dvanced-EDutput %ormat" MP%= PIC-GSM" Dutput" C#$ rray@ dvanced-EDutput %ormat" MP%=Classic If you are usin* the PIC-?=M board+ copy the resultin* .c file to your proFect directory+ over!ritin* the old one and compile the proFect 9see belo! for details about compilin* from sources:. If you are usin* any of the other boards+ you Fust need to upload the resultin* .bin file to the board. There is one or more method available dependin* on the board type you use. If you are usin* PIC-WEB or PIC-M >I-WEB you can upload a ne! ima*e throu*h the serial port. Enter the menu on the serial port and choose BDo%nloa& MPFS image C+ then use your terminal pro*ramAs send function !ith a >modem protocol - if you are usin* .yperTerminal on Windo!s+ this is available at the BTransfer->Sen& FileC menu. If you are usin* a PIC-MIC2D-WEB+ PIC-M >I-WEB or PIC-P&'(&) you can upload the .bin file directly from your !eb bro!ser. ?o to the pa*e http://board !p addr"##/$p%#&p'oad and use the !eb form. 5BG Internet E;plorer is broken and sometimes the upload fails. Please use another bro!ser. If you have a PIC-WEB or PIC-MI5I-WEB you can use an ftp client to upload the file to the board. Dne such client available on every Windo!s Installation is the command-line %TP.E>E. To use it+ start a command prompt 9Start menu->'un->Cm&(e$e: and chan*e to the directory !here your file is located e.*. if it is located in Bc)\tests\pic*%e"\ C type" c)\> c& tests\pic*%e" Then start the terminal client to your board and+ after a successfull lo*in+ send the file" c"HtestsHpicI!ebE ftp "oar&*ip*a&&ress +e(g( ,-.(,/0(1(.2.3 Connected to #7-.#&$.).-1-. --) 2eady Jser 9#7-.#&$.).-1-"9none::" ftp 11# Pass!ord reKuired Pass!ord" -1) <o**ed in ftpE put %e"("in

C+MPI,I05 T7E S+URCES

fter you have fulfilled the reKuirements+ do!nload the sources from the addresses *iven above and e;tract them. Then start up MP< B and load the appropriate proFect+ e.*. D<IME>IM >IWEB.mc!+ D<IME>IP&'(&).mc!+ etc. fter you have compiled the proFect+ you should be able to pro*ram the board. 5ote that if you pro*ram the board usin* the B4ebu**erC menu+ it !ill !ork !hen ran from the MP< B but the board !ill 5DT !ork later in standalone mode 6 you should use the BPro*rammerC menu instead.

Modi:$ing the stack to support additiona/ :eatures

The soft!are stack that runs on these boards can easily be modified to accommodate for different userAs needs. Kuick run-do!n of the different features available is *iven belo!

+ er iew
There are t!o different http servers available in the stack 6 .TTP and .TTPI-. 4ependin* on the version used+ the interaction dynamic interaction bet!een the stack and the !eb pa*es displayed is handled in a different !ay

7TTP < the o/d ser er

This server is used in the PIC-WEB+ PIC-MI5I-WEB and PIC-?=M boards.

1$na8ic ariab/es
The dynamic variables and command handlers commands are *iven an uniKue number !hich must be defined9and lo*ically matched: in both the !eb pa*es and the source. n e;ample+ taken from an older revision of PIC-M >I-WEB is *iven belo!" The dynamic variables are defined in the !eb pa*es as a --byte he;adecimal value prefi;ed !ith a C(L+ e.*. C()aL. When the !eb server encounters such a variable in a .c*i pa*e that is to be sent to the user it e;ecutes the function !#'D 4TTP5et6ar+78T9 var: !#'D ref: 78T9; val3 !here the C*arL is the variable encountered+ Cr"%L is a callback counter used !hen this function needs to !rite multiple bytes to the client and +*a' is a pointer !here the function should !rite the output. %or e;ample to return the state of the button # the relevant code is"

in index.cgi Button1: %04<br> in maindemo_maxiweb.c #define VAR_DIGIN0 in%ut& inside HTTPGetVar() (#&e VAR_DIGIN0:

(0x04)

!o"ent#r$ %u&' button

)*#+ , B-../N0_I/ 0 111:1012 bre#32

5ote that if the data that needs to be returned reKuires e;tensive9and time consumin*: processin*+ this is best done asynchronously in the Pro,"##IO-. function and the only thin* done in /00PG"t1ar-. should be the actual outputtin* of the data. n e;ample of this is the temperature measurement" inside Pro,"##IO-.

t"% , )((4/RD))(5ADR678))2 if(.e"%er#ture>91:) ; t"% , t"% < 91:2 t"% ,=2 .e"%er#ture , :0 > t"%2 ? e+&e ; t"% , 91: < t"%2 t"% ,=2 .e"%er#ture , :0 < t"%2 ? @on*ert 10Abit *#+ue into A7@II &trinB ito#(.e"%er#tureC .6!D7trinB)2 <= This takes a lot of time inside HTTPGetVar() (#&e VAR_ANAIN_AN1: )*#+ , .6!D7trinBE(BF.6)refG2 if(.6!D7trinBE(BF.6)refG ,, 1H01) return I..D_6ND_/J_VAR2 e+&e if(.6!D7trinBE(BF.6)>>refG ,, 1H01 ) return I..D_6ND_/J_VAR2 return ref2
The above e;ample also sho!s the usa*e of the C r"%L variable in the /00PG"t1ar-. function in order to output multiple characters. Basically this function *ets called !ith an increasin* C r"%L until it returns a /00P EN2 O3 1AR.

6or8 processing
The other kind of interaction bet!een the !eb pa*es and the server is form processin*. Dnly the C?ETL method is supported by the server and each form must have itAs o!n uniKue id at both the stack source and the !eb pa*e. The handlin* is done by the /00PE4",C$d-. function that is defined as"

*oid I..D6xe(@"d(BF.6)) #rB*C BF.6 #rB()

!here ++ar5* is a pointer to the parameters passed by the C?ETL action and the ar5, is the number of parameters. The relevant code to set the t!o

relays in !6d"47,5!

is"

<for" "et'od,KBetK #(tion,K0K> <b>A(tion&< b><br>.oBB+e R68AF&:<br> <in%ut t$%e,K&ub"itK n#"e,K1K *#+ue,KR68AF:K>< in%ut> <in%ut t$%e,K&ub"itK n#"e,K0K *#+ue,KR68AF1K>< in%ut> < for"> in maindemo_maxiweb.c #define @GI_@!D_DIG/-. (0) #define @!D_R68AF1 (0x0) #define @!D_R68AF: (0x1) inside HTTP!xec"md() (o""#nd , #rB*E0GE0G < 1012 <= here we extract the value of action from above ) Jind out t'e (Bi fi+e n#"e #nd inter%ret %#r#"eter& #((ordinB+$) &Lit('((o""#nd) ; (#&e @GI_@!D_DIG/-.: *#r , #rB*E1GE0G < 1012 <= here we extract the value of name from above &Lit('(*#r) ; (#&e @!D_R68AF1: R68AF1_I/ M, 12 bre#32 (#&e @!D_R68AF:: R68AF:_I/ M, 12 bre#32 ? ?

7TTP% ser er
This server is used in the PIC-MIC2D-WEB+ PIC-M >I-WEB and PICP#&'(&) boards. The handlin* of the dynamic content is Kuite different from the old server and because of that the t!o servers are discussed separately.

1$na8ic ariab/es
4ynamic variables are defined in the !eb pa*es in the format CMNvariableInameEML 9e.*. C8*"r#!o68L:. When the filesystem ima*e is *enerated by the MP%=- utility+ it also *enerates an include file called .TTPPrint.h that needs to be placed in the proFectAs directory. This file contains the declarations of the functions that return the respective variables 6 in the above e;ample the function handlin* the variable 8*"r#!o68 !ill be"

*oid I..DDrint_*er&ion(*oid)2
This function should be defined in one of the source files and *enerally Fust uses one or more of the /00PP&t+-. family of functions to output the

strin* that needs to be displayed to the user. =o the actual function !ill look like"

*oid I..DDrint_*er&ion(*oid) ; .@DDutR/!Arr#$(&3tI..DC(R/! *oid))V6R7I/NC &tr+en%B"((R/! ('#r))V6R7I/N))2 ? where the VERISON constant is defined as #define V6R7I/N K*4N1OK

6or8 Processing
%orm processin* in the .TTP- version of the stack is also very different. Both the C?ETL and CPD=TL methods are supported and are handled differently.

7TTP =5ET> hand/ing

When the client *enerates a .TTP C?ETL reKuest+ it is dispatched to the .TTPE;ecute?et9: function in the relevant ;*4TTP pp(c file 9e.*. Ma$i%e"*4TTP pp(c:. Inside that function the first operation is to e;tract the filename of the form that caused the call. fter that+ the user can parse the rest of the parameters 9usin* /00PG"tAr5-. family of functions:+ and at the end return either a success or that the operation cannot be completed at this moment 9 /00P IO 2ONE or /00P IO WAI0ING respectively:. n e;ample of the function that handles the settin* of t!o <E4s throu*h a ?ET reKuest is *iven belo!"

I..D_I/_R67-8. I..D6xe(uteGet(*oid) ; BF.6 )%tr2 BF.6 fi+en#"eE:0G2 !DJ7GetJi+en#"e((urI..DNfi+eC fi+en#"eC :0)2 if(P"e"("%%B":r#"(fi+en#"eC K+ed&N(BiKC O)) ; %tr , I..DGetR/!ArB((urI..DNd#t#C (R/! BF.6 ))K+edK)2 &Lit('()%tr) ; (#&e 111: 86D1_I/ M, 12 bre#32 (#&e 1:1: 86D:_I/ M, 12 bre#32 ? ? return I..D_I/_D/N62 ?

7TTP =P+ST> hand/ing

The other form processin* method available is CPD=TL. This method does not reKuire all the data to be available at the start of the processin*+ so the len*th of the parameters is virtually unlimited. The handlin* is done in the /00PE4",&t"Po#t-. function that is Fust a dispatcher that calls the various /00PPo#t+-. functions based on the name of the file that caused the CPD=TL reKuest. These functions are basically the same as the /00PE4",&t"G"t-. function !ith the e;ception that if more data is reKuired that is not yet received it could return a /00P IO NEE2 2A0A and be called a*ain !hen that additional data is available. n e;ample is the /00PPo#t9C2-. function that is used to display a te;t to the <C4 on the PIC-M >I-WEB static 4TTP*I#*'9SU<T 4TTPPost<CD+voi&3

; BF.6 )%tr2 4/RD +en2 8oo3 for t'e +(d &trinB +en , .@DJindR/!Arr#$(&3tI..DC (R/! BF.6 ))K+(d,KC 4C 0C JA876)2 If not foundC t'en t'roL #L#$ #+"o&t #++ t'e d#t# Le '#*e #nd #&3 for "ore if(+en ,, 0xffff) ; (urI..DNb$te@ount A, .@DGetArr#$(&3tI..DC N-88C .@DI&GetRe#d$(&3tI..D) A 4)2 return I..D_I/_N66D_DA.A2 ? .'roL #L#$ #++ d#t# %re(eedinB t'e +(d &trinB (urI..DNb$te@ount A, .@DGetArr#$(&3tI..DC N-88C +en)2 8oo3 for end of 8@D &trinB +en , .@DJind(&3tI..DC 151C 0C JA876)2 if(+en ,, 0xffff) +en , (urI..DNb$te@ount2 If not foundC #&3 for "ore d#t# if((urI..DNb$te@ount > .@DI&GetRe#d$(&3tI..D)) return I..D_I/_N66D_DA.A2 Dre*ent buffer o*erf+oL& if(+en > I..D_!AQ_DA.A_86N A :) +en , I..D_!AQ_DA.A_86N A :2 Re#d entire 8@D u%d#te &trinB into buffer #nd %#r&e it +en , .@DGetArr#$(&3tI..DC (urI..DNd#t#C +en)2 (urI..DNb$te@ount A, +en2 (urI..DNd#t#E+enG , 1H012 %tr , I..D-R8De(ode((urI..DNd#t#)2 %tr , I..DGetR/!ArB((urI..DNd#t#C (R/! BF.6 ))K+(dK)2

@o%$ u% to R: ('#r#(ter& to t'e 8@D if(&tr+en((('#r))(urI..DNd#t#) < R:u) ; "e"&et(8@D.extC 1 1C R:)2 &tr(%$((('#r))8@D.extC (('#r))%tr)2 ? e+&e ; "e"(%$(8@D.extC (*oid ))%trC R:)2 ? 8@D-%d#te()2 &tr(%$%B":r#"((('#r))(urI..DNd#t#C (R/! *oid))Kfor"&N't"K)2 (urI..DN'tt%7t#tu& , I..D_R6DIR6@.2 return I..D_I/_D/N62 ?

Revision history: REV.A REV.B - created April 2008 - updated December 2013

Disclaimer: 2008 Olimex Ltd. All ri !t" re"er#ed. Olimex$% l& & a'd c&mbi'ati&'" t!ere&(% are re i"tered trademar)" &( Olimex Ltd. Ot!er term" a'd pr&duct 'ame" ma* be trademar)" &( &t!er". +!e i'(&rmati&' i' t!i" d&cume't i" pr&#ided i' c&''ecti&' ,it! Olimex pr&duct". -& lice'"e% expre"" &r implied &r &t!er,i"e% t& a'* i'tellectual pr&pert* ri !t i" ra'ted b* t!i" d&cume't &r i' c&''ecti&' ,it! t!e "ale &( Olimex pr&duct". -eit!er t!e ,!&le '&r a'* part &( t!e i'(&rmati&' c&'tai'ed i' &r t!e pr&duct de"cribed i' t!i" d&cume't ma* be adapted &r repr&duced i' a'* material (r&m except ,it! t!e pri&r ,ritte' permi""i&' &( t!e c&p*ri !t !&lder. +!e pr&duct de"cribed i' t!i" d&cume't i" "ub.ect t& c&'ti'u&u" de#el&pme't a'd impr&#eme't". All particular" &( t!e pr&duct a'd it" u"e c&'tai'ed i' t!i" d&cume't are i#e' b* OL/0E1 i' &&d (ait!. 2&,e#er all ,arra'tie" implied &r expre""ed i'cludi' but '&t limited t& implied ,arra'tie" &( merc!a'tabilit* &r (it'e"" (&r purp&"e are excluded. This document is intended only to assist the reader in the use of the product. OLIMEX Ltd. shall not be liable for any loss or damage arising from the use of any information in this document or any error or omission in such information or any incorrect use of the product.