ETH3 CGI Common Gateway Interface user manual

Transcription

1 ETH3 CGI Common Gateway Interface user manual ETH3 web page server and Ethernet gateway CGI user guide Page 1

2 This is help.htm file stored in USB. The ETH3 gateway and web server from version has support to store user files in the USB memory where the user can easily personalize the web pages look and feel as well as create a unique and intuitive user interface. To be able to use this new feature it is necessary to understand a little bit on the internals of how the ETH3 allows to use a CGI "Common Gateway Interface" (a script standard for writing interactive programs generated by visitors to web pages). A full manual describing it's use can be found in the ETH3 CGI user manual The ETH3 runs on a Microchip PIC32MX795F512Lmicrocontroler that has five memory sections which are depicted below: (a). 128K of on-chip RAM memory not accesible to the user directly but where the NX and ETH3 database are stored. (b). 524K of on-chip FLASH memory used to store the ETH3-OS and is the memory updated when loading the firmware via USB. (c). 32K of NVRAM memory, used to store the ETH3 database (800 PLS instructions, 200 schedules 2250 remote points, 300 setpoints, etc). (d). 2MB of serial SPI FLASH memory used to store the ETH3 web pages. This memory has low latency fast access (<1ms) for opening, reading and closing the web files. (e). An externally mounted USB memory that supports standard USB-OTG with a FAT-32 system where user customized web pages can be added. The ETH3's locally hosted webpages must fit in the (d). 2MB of serial SPI FLASH memory and they are formatted using Microcgip's MPFS2 file system for fast acces. Statically linked dynamic variables present in *.HTM files are converted by the gateway into live data when the wabe pages are requested. These kind of variables can only be added, deleted or modified in conjunction with the source code of Microchips TCPIP stack so it is ulikely the user will want to do so do to the complexity of this task. To overcome this limitation, the (e). Externally mounted USB memory can be used to host user web generated web pages. Working in conjunction with the ETH3-OS's that allows the creation by the user of dynamic variables that can be insterted on the fly, the web page files can be uploaded/downloaded - to/from the development PC to the target USB mounted in the external connector on the ETH3. When a USB file is requested, it passes thru this CGI and the special CGI tags are converted to live values. Further using forms, the values of the variables which can be either hardware I/O, ram or NVRAM registers can be easily altered. In able for the ETH3's natively loaded web pages to be able to load user created files, special "hook" files are incorporated in the 2MB flash memory. These 51 files are named: "wf-0.htm" and up to "wf-50.htm" and their contents are simply hooks to staticaly created dynamic variables: ~usb_file(0)~ to ~usb_file(50)~ that the CGI knows how to interpret an call the respective files. ETH3 web page server and Ethernet gateway CGI user guide Page 2

3 For this to work, an index file called: "web_idx.ini" should be created in the USB inside the folder "_OpenBAS" which should be created in the root of the USB disk. The easiest way to get started is to copy the directory and all its contents that was added during the installation in C:\OpenBAS\ETH3_WebPagesUser\_OpenBAS\*.* to a USB memory and insert it in the ETH3where it will be mounted. Once the USB is mounted, every time a hook file is requested, the ETH3 opens the root index file "web_idx.ini" and checks which user file should be loaded and reads the file's contents, marshals the file it thru the CGI which does the dynamic conversion of the database variables stored as CGI tags into a live value that wil be finally sent to the browser and rendered accordingly. For examples on how to use the CGI refer to the example in the file "uindex.htm", if neessary view the web page source file, as it is heavily commented to help the developer into the creation of dynamic CGI tags and forms to modify values. Whereas the SPI internally stored web pages have a low latency of less than 1ms to access the file contents, the web pages stored in the USB depend on a library and the USB's own disk access OS to access the files, so time latencies of between 50 ms and up to 500 ms are normal to see. So any big files such as: images, CSS files, big data files is preferable to store in an external file or web server. This has the added advantage that these files can be shared among as many ETH3 web server/gateways thus creating a seamless user interface between accessing different ETH3 web servers. So having said this, keep the contents of the 51 USB files compact, and all images, CSS and other common files store elsewhere so thet can be accessed by the browsers that will be interfacing with the ETH3's web page files. Happy web page serving! ETH3 web page server and Ethernet gateway CGI user guide Page 3

4 This is the main page coming from first hook index file named: root.htm stored in the USB memory inside folder _OpenBAS With the links at the bottom, files can be uploaded and downloaded. ETH3 web page server and Ethernet gateway CGI user guide Page 4

5 The last link provides a view of all hooked files as listed in file web_idx.ini The contents of the hook index file web_idx.ini are shown below ETH3 web page server and Ethernet gateway CGI user guide Page 5

6 This is a hook file uindex.htm as rendered in a web browser: If selecting View page source additional help can assist on the creation of web based user interfaces. Following is the full listing to create this web page: <!doctype html> <meta http-equiv="refresh" content="20"> <html> <head> <title>openbas-nwk-eth3</title> <link rel="stylesheet" type="text/css" HREF="nx5.css"> </head> <body background="bkg_2.jpg"> <header> Web page server and network gateway. </header> <nav><center> <table cellpadding='4'> <tr> <td> <a href="index.htm"> Home </a></td> <td> <a href="es_1.cgi"> Inputs / Outputs </a></td> <td> <a href="remotos.cgi"> Remote points </a></td> <td> <a href="ajustes.htm"> Set points </a></td> <td> <a href="graficas.htm"> Trend log </a></td> <td> <a href="conf_nx5.htm"> Configure </a></td> <td> <a href="about.htm"> About OpenBAS </a></td> </tr> </table> </center></nav> ETH3 web page server and Ethernet gateway CGI user guide Page 6

7 <section><article> <center> <b> I am the file "uindex.htm" stores in USB </b><br> <hr> <b>here a sample of how to view the dynamic variables of ETH3's dynamic CGI<br> Use the CGI format: %TYPE-NUMBER-FLAGS% here the hardware I/O of the NX</b><br> For analog inputs AI-1 to 3 [%AI-1-fF1%] AI-2[%AI-2-fF2%] AI-3[%AI-3-fF3%]<br> For analog outputs AO-1 [%AO-1-fF1%]<br> For binary inputs BI-1 [%BI-1-fF1%]<br> For binary outputs BO-1 [%BO-1-fF1%]<br> <hr> <b>hook files WF[%WF-0-fF1%] which are indexed by root index file ZERO</b><br> Hook file 0 (main root indexfile) WF[%WF-1-fF1%]<br> Hook file 1 stored in USB memory WF[%WF-2-fF1%]<br> Hook file 2 stored in USB memory WF[%WF-3-fF1%]<br> Hook file 3 stored in ETH3's flash memory <a href="%wf-3-ff1%"> View remote points </a><br> <hr> <b>variables stored in EEPROM<b><br> 32 bit ADF float value DF[%DF-1-fF1%] <b>change it's value using forms:<b> <form method="get" action="adx.htm"> <input type="hidden" name="region" value="adf"> <input type="hidden" name="objnr" value="1"> <input type="text" name="value" value="%df-1-ff3%" size="10" maxlength="10"> <input type="submit" name="btn" value="ajustar"> </form><br> 16 bit ADF float value DI[%DI-1-fF1%]<br> DB[%DB-1-fF1%]<br> <hr> <b>some more variables from RAM<b><br> Result bit register RB-1 [%RB-1-fF1%]<br> Reult float register RF-1 [%RF-1-fF1%]<br> Timer TM-1 [%TM-1-fF1%]<br> Remote point RP-1 [%RP-1-fF1%]<br> Schedule HR-1 [%HR-1-fF1%]<br> Trend graph GR-1 [%GR-1-fF1%]<br> <hr> <b>now a link to the internet...<b> <a href=" </a><br> <b>load an image from ETH3's flash memory<b><br> <img src="minion.jpg" alt='minion' width='35'><br> <b>now some action using forms: Turn on and off binary outputs 1 and 2 (relay 1 and 2) and view it's state graphically instead of textually<b><br> <form method="get" action="on.htm"> <img src="_%bo-1-fv%%bo-1-fovs%.jpg" alt='???' width='35'> <input type="submit" name="rly1" value="0" > <input type="submit" name="rly1" value="1" > <input type="submit" name="rly1" value="auto" > </form><br> <form method="get" action="on.htm"> <img src="_%bo-2-fv%%bo-2-fovs%.jpg" alt='???' width='35'> <input type="submit" name="rly2" value="0" > <input type="submit" name="rly2" value="1" > <input type="submit" name="rly2" value="auto" > </form><br> <b>load an image from the internet<b><br> <img src=" alt='rs converter JPG file' width='50'><br> <!-- Finally add the footer to be consisten with ETH3's header/footer style and render the web page nicely --> </center> </article> </section> </html> </body> <footer> <b>eth3 web page server and network gateway footer created in user web page.</font> </b> </footer> ETH3 web page server and Ethernet gateway CGI user guide Page 7

8 This is a hook file help.htm as rendered in a web browser: And finally this is a hook file user.htm as rendered in a web browser: ETH3 web page server and Ethernet gateway CGI user guide Page 8

9 CGI tag syntax To correctly create tags that the ETH3 can understand they must adhere to the following format %TYPE-INDEX-FLAGS% Where the % percent character at the beginning and the end of the tag, are the opening and closing delimiters. If you want to add the percent character in your HTML file alone there are two ways to do it: Create an empty CGI tag with two percent characters %% Or embed an HTML character code % where the 37 corresponds to ASCII code for the % character, this way any character between can be embedded into an HTML page. Following is an ASCII character code and its codes that can be used in HTML: Following the opening % character is the type of the variable to be dynamically converted by the CGI, on the following pages the codes for each object in the database are described: ETH3 web page server and Ethernet gateway CGI user guide Page 9

10 ETH3 SOFTWARE (NX) HARDWARE (NX) Table of TYPE on the database highlighted in yellow, it must be at two character code telling the CGI which variable type is being addressed: Variable type TAG Low range High range name value defaults to 3 decimals value 0, 1, 2, 3 decimals status override active description ON/OFF Apagado/ Encendido Abierto/ Cerrado Normal/ Alarma Graphing Scheduling Analog inputs AI 1 40 fn fv ff0.. ff3 - fd fbon fbae fbac fbna Binary inputs BI 1 40 fn fv ff0.. ff3 - fd fbon fbae fbac fbna Analog outputs AO 1 10 fn fv ff0.. ff3 fovs fd fbon fbae fbac fbna Binary outputs BO 1 40 fn fv ff0.. ff3 fovs fd fbon fbae fbac fbna Lighting groups BO fn fv ff0.. ff3 - fd fbon fbae fbac fbna Floats 32 bits EEPROM DF fn fv ff0.. ff3 - fd fbon fbae fbac fbna Words 16 bits EEPROM DI fn fv ff0.. ff3 - fd fbon fbae fbac fbna System clock Bytes 8 bits EEPROM DB fn fv ff0.. ff3 - fd fbon fbae fbac fbna System timers TM 1 16 fn fv ff0.. ff3 - fd fbon fbae fbac fbna RES_FLT result float register RAM 32 bits RES_BIT restult bit RAM 1 bit RF fn fv ff0.. ff3 - fd fbon fbae fbac fbna RB fn fv ff0.. ff3 - fd fbon fbae fbac fbna Remote points via field busses RP fn fv ff0.. ff3 - fd fbon fbae fbac fbna Schedules HR fd Graph trend points GR fd see GR ranges see HR format System real clock time HR ftm Remote points fieldbus ETH3 via COM1 Remote points fieldbus ETH3 via COM2 RP fv ff0.. ff3 - fd fbon fbae fbac fbna RP fv ff0.. ff3 - fd fbon fbae fbac fbna Remote points IP RP fv ff0.. ff3 - fd fbon fbae fbac fbna Set points 32 bits DI fv ff0.. ff3 - fd fbon fbae fbac fbna Set points 16 bits DB fv ff0.. ff3 - fd fbon fbae fbac fbna Set points 18 bits HR fv ff0.. ff3 - fd fbon fbae fbac fbna Schedules HR fd Hook to USB web files WF 0 50 fn fd see HR format - Following the TYPE and separated with a hyphen is the INDEX or object number, which must be between the ranges shown in the table above in the columns: LOW RANGE and HIGH RANGE inclusive. Finally after the INDEX and also separated by a hyphen, follows the FLAG field with the different flags shown in the table in all the sections labeled as FLAGS. Finally to close the CGI tag the % character must finish the tag, no spaces are allowed inside the CGI tags. For examples on using the graph sample points refer to the source code of the web pages in the flash files stored in the directory: C:\OpenBAS\ETH3_WebPagesUser\ETH3_flashWebPages\protect\graf_*.cgi To print the real time clock use for example the CGI tag: %TM-1-fTM% For additional examples refer to the rest of the source file in the same directory and for user examples for the files in the user web pages located in: C:\OpenBAS\ETH3_WebPagesUser\_OpenBAS\*.* ETH3 web page server and Ethernet gateway CGI user guide Page 10

11 Generating the ETH3 flash web pages As mentioned before, the ETH3 has an integrated 2 MB Flash memory attached to the main microcontroller via the SPI bus. The web pages stored there are accessed with very low latency and are formatted into a single image file using the MPFS2 (Microchip File System 2). Normally there is no need to recreate this file as a previously generated BIN file is always present in the HEX files located for the web server located in: C:\OpenBAS\_NX5 version \Bootloader\_HEXfiles\OpenBAS\1105_OpenBAS_NWK_ETH3--32bit As depicted in the image below: Take note that the directory name as well as the file name will reflect the current version. However if by some reason when customizing a web server the files ever need to be modified which is not recommended now the user modifiable web pages are available via USB, all the source web pages to generate the BIN image file that can be downloaded to the web server are located in the directory: C:\OpenBAS\ETH3_WebPagesUser\ETH3_flashWebPages There is a batch file that can be used to call the utility to create the MPFS2 formatted image file: C:\OpenBAS\ETH3_WebPagesUser\ETH3 flash MPFS2 web page generator.bat ETH3 web page server and Ethernet gateway CGI user guide Page 11

12 When double clicked will open the MPFS2 image generator. Make sure that the correct path is being selected in the source directory, also make sure the Webpage directory option is selected: Then make sure that the BIN image generation option is selected: The BIN file containing the web pages selected in Image Name will be created in the Project Directory selected, make sure that the paths are correct: Optionally the generated BIN file can be automatically loaded if the IP of the ETH3 is already available: ETH3 web page server and Ethernet gateway CGI user guide Page 12

13 When pressing the Generate and Upload button the file containing the FAT and the web pages will be created and uploaded to the web server as shown below, the progress indicator will show how much of the file has been uploaded. After the upload completes, a pop up window will indicate so. You can verify that the newly created MPFSimage2.bin file was created along two other files: HTTPPrint.h and HTTPrint.idx. ETH3 web page server and Ethernet gateway CGI user guide Page 13

14 If by any chance you make extensive changes that affect the dynamic mapping of the web page files, a warning stating that the dynamic variables changed and the MPFSimage2.bin file might not work correctly in conjunction with the web server. This is the main reason why it is not recommended to modify the original source web pages, because the risk of un-synchronizing the web pages with the web server. However on every release as things might change, the source web pages will be provided for if you decide to embark into a highly customized web server. The generated MPFSimage2.bin can always be loaded from the web browser window, to do so follow the following procedure: First make sure you can access your web server by typing it s address in the URL edit field on your browser: ETH3 web page server and Ethernet gateway CGI user guide Page 14

15 Second, when you can access your web server that will be updated, add an X after the IP address, (any name will be OK as we just want to force the web server into update mode) this will force the web server to request that you provide directions to upload the file. Select the hyperlink labels MPFS Upload and this will bring another web with a Browse button that will allow you to search for the generated BIN file: C:\OpenBAS\ETH3_WebPagesUser\MPFSImg2.bin After selecting the file, press the Upload button and it will take around a minute to transfer the file into the web page server, after that a new screen will provide you with a link to go to the web server s main page: ETH3 web page server and Ethernet gateway CGI user guide Page 15

16 IMPORTANT NOTE Take into consideration that if you add files to the directory containing the web page source files, you might exceed the maximum size of 2 MB and because some of this space is used internally, you must limit the size to be no more than 1.9 MB for correct operation. ETH3 web page server and Ethernet gateway CGI user guide Page 16