-
Notifications
You must be signed in to change notification settings - Fork 2
Home
Welcome to the OliWeb wiki!
OliWeb is designed to be an ultra-lightweight web server to act as a means of controlling or monitoring projects on a Raspberry Pi remotely via a web browser (mobile or otherwise). It is a very fast, native-code web server with very low memory consumption. It works on most *NIX systems including Raspbian, Ubuntu, and OS X. OliWeb's installation is simple by design - you can have it up and running in less than five minutes. OliWeb has built-in support for Python, PHP, and shell script invocation via a simple CGI mechanism. Within minutes of installation, your hobby project on the pi can be web-enabled.
OliWeb makes the absolute minimum passable attempt at HTTP/1.1 standard compliance to be able to convince all tested browsers to render delivered content correctly (which, to date, includes IE9, Firefox, Safari for OSX, Safari for iOS, and Chrome for OSX and Windows).
OliWeb ships with a number of utilities, scripts, and integrated examples that interact with GPIO pins to enable you to control your projects from your favorite browser. See the "bells and whistles" section below for further details.
OliWeb has been tested on several linux variants running on Raspberry pi including Raspbian and TinyCore Linux.
OliWeb has also been tested on Intel-based linux platforms (Ubuntu 12.10 / 64-bit VM running on MacBook Pro).
Update: Now works with BSD / OS-X as well after fixing some goofy socket code.
Update: Confirmed to work with C.H.I.P. computer.
Android, iOs, Windows, EtchaSketch
If you are looking for an ultra-lightweight web front-end to enable you to create web interfaces to your Raspberry Pi that
- is simple to install and run
- requires minimal system resources
- is fast and responsive
- provides a trivially simple content management scheme
- provides a trivially simple interface for invoking functionality and passing arguments on the Pi (REST services)
- can be used to easily integrate functionality on your pi with any browser or HTTP client
- readily integrates with PHP or Python
then OliWeb may be a good solution for you.
In testing, OliWeb has run for months at a time with a memory footprint of under 1.8MB (1.8MB RES, 1.2MB SHR). OliWeb spins up separate handlers for each inbound request, so memory consumption will increase under load (based on concurrent request count). When hit with 400 simultaneous requests in scripted load testing the footprint stayed below 5MB (RES). CPU consumption under heavy load testing did not exceed 5% (testing was from a remote server - higher network bandwidth will enable higher throughput and hence higher CPU utilization, so YMMV).
If you are looking for a server that
- is guaranteed 100% HTTP protocol-compliant
- is designed for hosting integrated content management software
- will host your eCommerce site, blog, Wordpress, what have you
- you want to do ASP, J2EE, FastCgi, or other such fancy things
- security?
then there are lots of great options out there for you like nginx, Apache, and LightPd. OliWeb isn't meant to compete with any of these fine offerings but rather to sit to well to the left of them on the continuum spanning utmost simplicity and minimal footprint through full-featured functionality, full protocol standards compliance, and robustness.
- Clone from GitHub ("git clone [url from git page]")
- Go to the ivySox folder ("cd OliWeb/ivySox")
- Build the web server ("sudo make all")*
- Run in background mode ("./OliWeb &")
At present, it is recommended that you only invoke OliWeb from the directory in which the binary resides (future planned enhancements will be more flexible on this but today it will cause problems with finding configs, web source, cgi scripts, etc.).
OliWeb is written in C++. In order to make it, you will need to have g++ installed.
By default, OliWeb listens on port 8077. In order to access it from your browser or HTTP client, use the URL "http://[myPiIpAddress]:8077", where [myPiIpAddress] is your pi's IP address (e.g. "192.168.1.107").
- It's recommended to make with sudo since some of the install directives may bomb on you without superuser rights.
##Auto-run Setup
You only need to perform this setup if you want OliWeb to automatically run on startup of your machine.
There is an included script called "install.sh". Running "sudo ./install.sh" after building OliWeb will do the following:
- Copy the latest binary to /usr/local/bin
- Copy the local config file (OliWebConfig.xml) if one does not already exist in /usr/local/bin
- Copy a startup script out to /etc/init.d location
- Will notify the system that there is a new startup script
When this is done, OliWeb will automatically run on boot. You will need to modify the config file (/usr/local/bin/OliWebConfig.xml) to reflect the absolute paths of the web, util, and cgi-bin directories.
When "make all" is invoked, there are a number of build targets:
- OliWeb (the web server executable)
- GetProperty (simple utility for retrieving values for defined properties in URL query strings)
- Install (sets permissions on scripts and utilities to 775 so they can be executed at runtime)
The 3rd step requires necessary permissions. Depending on your user rights, you may have to build with "sudo make all". If you want to have less permissive settings on scripts/utilities for whatever reason, you can modify the install target in the Makefile in OliWeb/ivySox to do so.
There are a handful of web pages, images, and scripts pre-installed in the "web" and "cgi-bin" folders. These are provided for the purposes of illustration and testing only. A number of the cgi scripts are tied to GPIO sensing/manipulation functions, some of which leverage Gordon's wiringPi utilities which can be found here. However, neither compilation nor execution of OliWeb have any direct dependency on wiringPi... this is purely optional and not included in the OliWeb distribution.
An additional command-line utility is included which enables easy extraction of property values from a URL query string. Use of this utility to extract parameter values from the string within a BASH script is illustrated in the "test.cgi" script included in cgi-bin. Python and PHP have their own way of doing this - examples are included for both.
NEW - Included is the OliWeb location tracking app. It's built in Bootstrap/jQuery/javascript/HTML5, and logs your location on the server when tracking is enabled. You can then use the map charting page to display paths. The tracker logs location with time code - new features are planned for this in the future.
For the purposes of maintaining compatibility with the git repository, it's best to leave the "web" and "cgi-bin" directories that are pre-installed alone along with the sample files contained within them. To customize the content delivered by your web server, it's recommended that you create a new root folder for web content and/or a new folder for cgi scripts. For example:
mkdir MyWeb
mkdir MyCgi
Then change the relevant settings in OliWebConfig.xml (see "Configuration Settings").
Configuration settings can be changed in the file OliWebConfig.xml. The default settings are shown below.
<?xml version="1.0" encoding="utf-8" ?> <OliWebConfig> <ConfigurationSettings> <PortNumber value="8077"></PortNumber> <RootFileDirectory value="web"></RootFileDirectory> <DefaultFileName value="index.html"></DefaultFileName> <FileNotFoundPage value="oops404.html"></FileNotFoundPage> <ScriptDirectory value="cgi-bin"></ScriptDirectory> </ConfigurationSettings> </OliWebConfig>
Port Number - This sets the port that OliWeb will listen on for inbound requests. By default it is set to a non-standard HTTP port because many ISPs block port 80 for external access. You can change this to anything you want (including HTTP-standard port 80).
RootFileDirectory - This enables changing the root directory for content. At present, this directory must be directly nested under the ivySox directory in order for the server to find its content. Additional folders can be added under this folder and content accessed via URL (for example, accessing "http://192.168.1.107:8077/MyNestedFolder/SomePage.html" from the browser will cause OliWeb to look in "web/MyNestedFolder" (with default RootFileDirectory settings) for the "SomePage.html" file.
To create your own customized content to be hosted by OliWeb, it is recommended that you create a new directory other than the default "web" directory and configure this setting accordingly.
DefaultFileName - Usually you want this to be "index.html" which is the standard behavior when no specific file is included in the url. But you can change it. If you want to.
FileNotFoundPage - Likewise, whatever content you want displayed for a 404 error can be set here.
ScriptDirectory - This determines where OliWeb will look when trying to invoke CGI scripts. Currently only bash shell scripts are supported for cgi execution (they're invoked in child processes differently than native binaries, but it's on my to-do list to get those working as well). Binaries can of course be invoked as child processes via shell scripts. The extension for scripts placed in this directory must be ".cgi" or ".CGI" to tell OliWeb that these should be executed rather than fed back as text to the web server. See the section on "CGI Scripting" for further usage instructions.
LogFile - By default, OliWeb.log in executing directory. You can redirect this anywhere you please. If you want to turn web logging off, configure logs to /dev/null.
To create your own customized scripts to be hosted by OliWeb, it is recommended that you create a new directory other than the default "cgi-bin" directory and configure this setting accordingly.
OliWeb includes a mechanism for invoking shell scripts via URL in order to enable implementation of web services and parsing of simple input forms. Any URL consisting of a filename with a ".cgi" or ".CGI" extension will cause OliWeb to look in the scripting directory (including nested relative-path folders if included in the URL) and execute the script (rather than serving it up as text content to the browser).
All scripts executed by OliWeb will execute from the path in which OliWeb was invoked (nominally, the ivySox directory). Therefore, if calling other utilities, they need to be either globally path-accessible (such as in usr/local/bin), or invoked with path relative to the OliWeb invocation directory (nominally ivySox). If you want to execute one CGI script (invoked_script.cgi) from another (invoker.cgi), for instance, your invoker script would need to call as follows:
cgi-bin/invoked_script.cgi
The "ivySox/util" directory is provided as a place to put helper scripts or programs that are not globally-pathed that you want to invoke from within a CGI script. For example, you may have a utility (MyUtility) that you want to call from within a CGI script. You would invoke this as
util/MyUtility
Many of the included scripts in cgi-bin illustrate how to work with relative paths from OliWeb-invoked scripts.
The URL query string is passed in to the executing program by means of the environment variable "QUERY_STRING" which is compliant with established CGI/1.1 practice. It is up to the invoked process to parse the query string to retrieve any arguments or properties contained in the URL. For convenience, a command-line executable program called "GetProperty" is included in the "util" folder.
The GetProperty program can be used as follows to extract the value for a named variable from the passed in $QUERY_STRING:
PARAMETER1="$(util/GetProperty parameter1 $QUERY_STRING)"
If for instance the requested url was "http://[myPiIp]/myScript.cgi?parameter1=dry¶meter2=white¶meter3=toast&piIsRoughly=3.14159", placing the above line of code into "myScript.cgi" would result in a value of "dry" being placed in the local environment variable "Parameter1" which you can then use to work wonders. Example "test.cgi" in the cgi-bin directory illustrates parameter extraction in this fashion. If you're a SED wizard or a Python person or what have you and would rather go that route for parsing arguments, go nuts.
OliWeb pulls the contents of standard out from the invoked CGI process and serves that up to the client, enabling dynamic content generation. Whatever goes to standard out is what will show up in the browser (whether formatted as HTML or as plain text or what have you).
OliWeb now supports HTTP POST operations as well, and passes the request body along to the handling CGI script. When doing form POST operations for example, the body is formatted in a manner consistent with the QUERY_STRING for GET operations, so the parsing utility described in the previous section can be used in the same manner to pull information out of the request body.
If there are additional CGI-compliant metaVariables that you need for your project, drop me a line (or file an issue on git) and I'll take a look at adding them.
OliWeb now supports PHP scripting (in alpha - still brand new - has not been extensively tested). To use PHP, you need to have a command-line PHP parser installed in /usr/bin/php.
[code] sudo apt-get install php5-cli [/code]
Any URL containing a requested file with '.php' or '.PHP' extension will be treated as PHP and the script results sent back as the HTTP response.
Please let us know if you have any issues in using PHP scripting - it is brand new and has not been heavily tested as of yet.
OliWeb logs all inbound requests in the file "OliWeb.log". It's fairly verbose in so doing, which has been very helpful for development and debugging purposes. In the future we may offer log level configuration to make this a little leaner (or absent) for those who don't want to keep piling up logging data.
This file is appended with each run of OliWeb so the previous contents are retained. There is no cleanup or archival process at present, so you may have to periodically delete the logs if they get too big.
No claims are made about the conformity of OliWeb to the HTTP/1.1 (or any other) standard. It is by design very simple and supports the minimum subset of the HTTP protocol such that it is able to service GET requests successfully to all tested browsers.
It has been tested and found to work (at one point or another) with IE9, Safari (iPhone/iOS 6.x), Safari (OSX), Safari (iPad/iOS 6.x), Mozilla Firefox (22.0), and Google Chrome. Given the minimalist approach to HTTP/1.1 compliance, it is possible (likely even?) that some of the snootier HTTP clients may complain or render content incorrectly. If you find this to be the case, drop me a note or file a bug and I'll try to add whatever minimal/incremental overtures of HTTP standards compliance required to pacify your picky, picky client app. (I didn't have response headers at all in the early version because Safari and IE don't seem to give a hoot... Firefox however is sort of uptight about not getting reassurance that everything went swimmingly in the course of servicing its request and, in the absence of same, does the browser equivalent of wetting itself (squirts out HTML pages that are obviously HTML pages as plain text)).
So, specifically, OliWeb includes HTTP response header information for only the following things:
- Status line for success (i.e. "HTTP/1.1 200 OK")
- Status line for FNF (i.e. "HTTP/1.1 404 Not Found")
- "Connection: close" header which is allegedly required by the standard and which could cause client-side confusion if not explicitly stated.
- A blank line following response headers as per the standard
- "\r\n" for line ends because the standard specifically decrees it
That's it. If your client app needs OliWeb to tell it what time it is, or when the requested content was last modified, or what the content MIME type is, or what your IP was when you requested the content, or where you pointed your URL when requesting the content, or where you left your keys, you're out of luck. If you absolutely need some specific piece of HTTP/1.1 header metadata populated to make your application work, drop me a line and I'll be happy to take a look.
#IvySox
IvySox is the socket listener and connection management object that hides all the icky c-language socket programming stuff and provides the network magic for OliWeb. If you're interested in using it for general-purpose network programming applications, you just need IvySox.h and IvySox.cpp.
I've included a very simple example program called "HelloSocket" in the distribution to illustrate how to use it. One you make the program, just run
./HelloSocket
to run on the default port # of 8077. If you want to change the port, it's the first and only argument to the program:
./HelloSocket [portnumber]
You can then use your browser to access the socket listener with
'http://[myPiIp]:[portnumber]'
which will echo back the contents of the HTML GET request back to the browser.
#Bells and Whistles
The OliWeb distribution ships with a number of utilities for controlling GPIO pins, as well as shell scripts and examples (accessible via the OliWeb default home page) for how to use them.
- gpioReadWrite - A simple utility for toggling pins (write mode) or polling pin status (read mode)
- gpio_pwm - A command-line utility that creates a PWM signal on a GPIO pin for driving servo motors (or what have you)
- Built-in web cam functionality (requires installation of fswebcam) - Use OliWeb to take and view snapshots from any USB webcam remotely
- NEW: HTML templates and scripts to leverage raspistill for the pi camera module
- NEW: Built-in GPS Tracker. Location tracking page uses JavaScript/jQuery in conjunction with mobile GPS to track your location (as long as web page is open). Web console will display location tracking data on Google maps.
Usage documentation to follow.