ETH3 CGI “Common Gateway Interface” user manual

ETH3 web page server and Ethernet gateway CGI user guide Page 1
This is help.htm file stored in USB.

The ETH3 gateway and web server from version 2.75.3 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
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
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
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
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"> &nbsp;&nbsp; Home &nbsp;&nbsp;</a></td>
<td> <a href="es_1.cgi"> &nbsp;&nbsp; Inputs / Outputs &nbsp;&nbsp;</a></td>
<td> <a href="remotos.cgi"> &nbsp;&nbsp; Remote points &nbsp;&nbsp;</a></td>
<td> <a href="ajustes.htm"> &nbsp;&nbsp; Set points &nbsp;&nbsp;</a></td>
<td> <a href="graficas.htm">&nbsp;&nbsp; Trend log &nbsp;&nbsp;</a></td> <td> <a
href="conf_nx5.htm">&nbsp;&nbsp; Configure &nbsp;&nbsp;</a></td>
<td> <a href="about.htm"> &nbsp;&nbsp; About OpenBAS &nbsp;&nbsp;</a></td>
</tr>
</table>
</center></nav>

ETH3 web page server and Ethernet gateway CGI user guide Page 6
<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: &#37;TYPE-NUMBER-FLAGS&#37; 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 &nbsp;&nbsp;&nbsp; <a href="%WF-3-fF1%">&nbsp;&nbsp;&nbsp; View remote points
&nbsp;&nbsp;&nbsp;</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> &nbsp;&nbsp;&nbsp; <a href="http://www.rikmed.com">&nbsp;&nbsp;&nbsp;
http://www.rikmed.com/ &nbsp;&nbsp;&nbsp;</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="http://www.rikmed.com//232-485.jpg" alt='RS232-485 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>

<footer>
<b>ETH3 web page server and network gateway footer created in user web page.</font> </b>
</footer>
</body>
</html>

ETH3 web page server and Ethernet gateway CGI user guide Page 7
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
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 &#37; where the 37 corresponds to ASCII code for the ‘%’
character, this way any character between 0…255 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
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:
Flag value Flag value Flag status Flag Flag Flag Flag
Flag Flag Flag Flag Flag
Variable type TAG Low range High range name
defaults to 0, 1, 2, 3
3 decimals decimals
override
active
description ON/OFF
Apagado/
Encendido
Abierto/
Cerrado
Normal/
Alarma
Graphing Scheduling
System
clock
HARDWARE (NX)

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 41 60 fN fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -

Floats 32 bits EEPROM DF 1 100 fN fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -

Words 16 bits EEPROM DI 1 100 fN fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -

Bytes 8 bits EEPROM DB 1 100 fN fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -
SOFTWARE (NX)

System timers TM 1 16 fN fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -

RES_FLT result float register
RAM 32 bits
RF 1 255 fN fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -
RES_BIT restult bit
RAM 1 bit
RB 1 255 fN fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -

Remote points via field busses RP 1 255 fN fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -
see HR
Schedules HR 1 200 - - - - fD - - - - -
format
-
see GR
Graph trend points GR 1 16 - - - - fD - - - -
ranges
- -

System real clock time HR 1 - - - - - - - - - - - - fTM

Remote points fieldbus ETH3
via COM1
RP 1 1000 - fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -
Remote points fieldbus ETH3
via COM2
RP 1001 2000 - fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -

Remote points IP RP 2001 2255 - fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -

DI 1001 1100
ETH3

Set points 32 bits - fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -

Set points 16 bits DB 1001 1100 - fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -

Set points 18 bits HR 1001 1100 - fV fF0.. fF3 - fD fbON fbAE fbAC fbNA - - -
see HR
Schedules HR 1 200 - - - - fD - - - - -
format
-

Hook to USB web files WF 0 50 fN - - - fD - - - - - - -

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