Web Server
This applies to devices fitted with and SD card and wi-fi module, currently the BV503 and BP2 wi-fi shield. It also requires ByPic version 2.08-28 or later as that has interpret() and floadp() functions.
The current devices that have wi-fi are BV503 and the BP2 shield. UART1 is used to transmit and receive information and so in theory the code can be used with any device capable of TX/RX to an external web browser. An SD Card though is necessary. The hardware page is here.
The web server described on this text is called webserver_e.bas and will run on any MX3 device that has an SD card fitted. Apart from the actual connection to the web most of the functionality of the web server is provided by this file.
Resources
Resources, the .bas programs and html files can be found with the relevant hardware, currently BV503 and BPS12 wi-fi link. However the web pages are reproduced here for reference purposes.
Update: webserver_f now has a watchdog timer.
Introduction
Web communications consists of a web browser and web server, fortunately the web browser has the most difficult job to do and it is in fact possible to create a web server with some very simple code. Most web servers are capable of handling multiple connections, this is not the case here as we only have the one UART.
The communication between a web browser and server is relatively slow and is simplex, meaning in this case the web browser does all of the communication initiation. If the server had something to say it has to wait for the browser to make a request, the server cannot 'push' information to the browser. It would not really be suitable for controlling a model car or plane for example although 'websockets' may be the answer there.
The real reason for using a browser is that every device has one from a smart phone to a PC. It is already installed and there is no additional set up. This makes it ideal for controlling any manor of devices from any manor of clients; the client of course can be as remote as you like.
An example would be the heating system of a holiday home (or workshop in my case). Use a smart phone to turn it on before you get there, monitor the current temperature etc.
HTML & ByPic
Unfortunately there is another language to learn if you don't already know it, if you do think 'php'. PHP is a scripting language built into all commercial web servers and the web server presented here is modeled in that fashion.
The idea is that it enables ByPic functions to be built into web pages to perform hardware functions. This is a real software to hardware interface; the browser is now capable to setting pins and reading real data. Mostly when setting or receiving data forms are involved although it can of course be done through a link. There are two distinct operations during communication and that is sending information to the server and receiving information from the server.
Receiving
When a browser requests a page via the URL, for example <some website>/page the page is found on the web server and sent back to the browser. For a shopping site this can be static information, the page will remain the same no matter what, but for a page that may represent say if a pin, or set of pins, are high and low then depending on the state of the pins the actual page sent back to the browser will vary - so how is this done?
This is where scripting comes in and it is better to explain this by an example.
This is the actual page served up by ByPic. Note that the values are the actual values from the ADC at the time the page was requested.
The URL: http://192.168.11.220:8000/analogue.html points to the web server and the page. The web server receives this as a GET request for the page analogue.html. This page of course must be on the SD card for ByPic to be able to serve it. ByPic more or less serves (sends it to the browser via UART1) the page as it, the cleaver bit is within the page itself.
The page has a table of 3 rows and 4 columns. Rows 1 and 2 contain static data that does not change, above is the code for the third column. Instead of a number as displayed when the page is served to the browser, some script has been added:
Taking the first column of that row if this were a static page then it would be
1] <td>865</td> (the is just HTML for a space and is not really needed)
2] However the actual code is : <td><?bypic echo$=adc_get(2) ?></td>
So how does this work? Anything placed between <?bypic and ?> will be sent directly to the ByPic interpreter, just as if it were typed in at the ok prompt. What this does is place the adc value of channel 2 into the variable echo$. This is a special variable who's value will be substituted instead of the script. So when the page is processed the value 865 is placed into echo$ and it is that value that replaces the script so the browser will see 1] above and not 2].
This page also has some other script at the top of the page.
Here the ADC values are initialised before being used. The format is slightly different in that the <?bypic and ?> are on separate lines. Functions, constants and variables can also be specified here but don't forget they can just as easily be specified on the SD Card or in Flash, this will reduce the page size. Also consider if it is desirable to initialise the ADC every time the page is loaded? See the next example for more information on this.
Further Example
Just to clarify some further points.
Here is the ports.html web page that displays the state of the pins on PORTB, if they are set to analogue, if they are set as input or output and the value if applicable.
This page consists mainly of a 16 x 4 table.
This is a code snippet from the A or D row and a function 'style_ad$(register,pin)' is called. The register in this case AD1PCFG will determine if the port is going to be analogue or digital. It is in fact just a number (register address), the name is related to a number in the 'rookie' file using a constant. The purpose of the function 'style_ad$(register,pin)' is to return a D or A suitably coloured.
For this example the function is at the top of the html page.
This function could just as easily been part of a ByPic set of functions loaded as part of the web server. It does though have a slight advantage in that the colour of the letters 'A' or 'D' is determined by an inline style called 'green' and 'cyan'. It can be seen that the function will return either:
t$ = "<span class='green'>D</span>"
or
t$ = "<span class='cyan'>A</span>"
Depending on the contents of the register and the value of the pin. The big advantage here is that register is generic and so this routine can be used for any register so this page can be expanded to other ports mostly by copy and paste.
<!-- This is an HTML comment and though not strictly necessary some wisiwg web page makers get upset with ?>bypic and so this makes sure that they will display okay whilst building the page. There is of course the corresponding --> at the end of the bypic code.
Forget it
When including functions, constants or variables as part of the web page like this, ByPic will compile them into memory each time the page is requested. As a page is quite likely to be requested many times, depending on the ByPic settings, the functions will be compiled each time and so the memory will become full.
To stop this happening a forget function is paced at the end of the page.
This will tell ByPic to forget any constants, variables and functions created after and including PORTSHTML. That is the only purpose of the constant at [27] above. The page can now be called any number of times without creating an overhead.
Sending
In this scenario the browser is used to set something, the speed of a motor, to turn the heating on for example. There are two main ways to do this, one is to use a link. A link simply requests another page, the server could recognise this and set one specific item.
A better method is to use a form as this can have buttons, check boxes etc. that is much more in keeping with setting things.
As an example see this page.
The page is called setting.html and indeed when first requesting the page the URL will be http://192.168.11.220:8000/setting.html. Observe the URL in the picture this will be dealt with later.
This is the code that creates the form that presents the buttons. When a button is pressed a request is made to the server, but this time the form action "ledReq" is sent along with the button name and value that has been pressed. Check box type forms may send several name, value combinations.
It can be seen in the URL in the picture that button 2, OFF has been pressed:
http://192.168.11.220:8000/ledReq?2=OFF
The server can process this information and there are some functions built into ByPic to help with this. The first thing to note about this (sending) process is that instead of a page name being in the URL, there is an action name 'ledReg' in this case.
The way that the web server has been coded is that there are two global variables page$ and line$, in this example when a button is clicked page$="ledReq" and line$="2=OFF"
ledReq is a subroutine that already exists in RAM or Flash that will take the "2=OFF" and with this information turn LED 2 off, all that remains is to call ledReq to do this. It could be done as a select/case statement but to make the web server more flexible, lookup() and exec() is used.
lookup() will return the address of a function if it exists, it returns 0 if it does not exist and exec() will call the function at the given address, so by looking up the function and calling it this will save a long list of case statements. It also means that one function can handle this without any modification when additional functions are added.
NOTE: When using exec() it always requires that the function called returns a value, a stack error will occur otherwise.
There is one last thing to do; when a button is clicked on the browser, it expects a page to be sent back even though in this case there is nothing new to send back it still has to be done and so in this instance we send back the original 'setting.html' page. This is probably unusual in that we are likely to send back some status information anyway, such as is the LED really on.
The web server has a global variable root$ for this purpose.
Page Creation
Just a final word about web pages and what the browser expects. For HTML 1.1, annoyingly as part of the first information to send is the page size in bytes. This is perfectly fine for a static page but what about a dynamic page where the length is not known until the whole page is parsed. For example
1] <td>865</td>
2]<td><?bypic echo$=adc_get(2) ?></td>
2) is the code in the html file but 1) is sent back to the browser, there is a 21 byte difference. The way to deal with this is to create the whole page first before sending it to the browser. On the current ByPic system there is not enough room to do this in RAM and so a temporary file (defined as a constant tempFile$) is created whilst parsing the page information and it is this temporary file that is always sent back to the browser.
To put this simply, from the dynamic page a static page is created and sent back to the browser.
Server limitations
The current server can't handle images or separate style sheets and of course the only scripting is ByPic. It should be a straight forward matter to be able to include images and external style sheets - volunteers required.