Commits

Sebastian Bub committed be2d963

added documenation of external commands

Comments (0)

Files changed (1)

 # RASPBERRY PI GPIO WEB CONTROL INTERFACE
 
-## A Java webapp to control your GPIO ports of the Raspberry Pi using http
+## Java webapp to control your GPIO ports of the Raspberry Pi using http or cronjobs
 
 
 ## What is raspberry-pi-gpio-web-control?
 
-raspberry-pi-gpio-web-control is a lightweight java based web application to control your GPIO ports
-of your Raspberry Pi over http. It is based on documentation at 
-[elinux.org: RPi Low-level peripherals](http://elinux.org/Rpi_Low-level_peripherals#GPIO_Driving_Example_.28Shell_script.29)
+**raspberry-pi-gpio-web-control is a lightweight java based web application to control your GPIO ports of your Raspberry Pi over http.**
 
-It is tested with [Winstone Servlet Container](http://winstone.sourceforge.net/), but any
+### Feature Summary
+
+* **Control GPIO ports over http**
+* **Conditions on input ports to set output ports**
+* **Fully integrates analog input with [RC circuits](http://en.wikipedia.org/wiki/RC_circuit)**
+* **Fully integrates any command/script, i.e. to handle SPI interface or send notifications**
+* **Cronjob integration**
+
+
+
+It is based on documentation at 
+[elinux.org: RPi Low-level peripherals](http://elinux.org/Rpi_Low-level_peripherals#GPIO_Driving_Example_.28Shell_script.29). It is tested with [Winstone Servlet Container](http://winstone.sourceforge.net/), but any
 other servlet engine will probably do, too.
 
 
-### Features:
+### Detailed Features:
 
-* Every port can be set as input, output or analog input (requires a simple circuit based on [raspberrypi-spy.co.uk: Reading Analogue Sensors](http://www.raspberrypi-spy.co.uk/2012/08/reading-analogue-sensors-with-one-gpio-pin/)).
-* Output ports can be set conditionally on values of input ports (i.e. darknessSensor1in==1&lamp1out=1, see cron.conf).
-* You can give each port a custom name to make your client look better.
-* You can define a default state on output ports.
-* You can define a blocking time for an output port (so it is not switched to
+* Every port can be set as input, output or **analog input** (requires a simple circuit based on [raspberrypi-spy.co.uk: Reading Analogue Sensors](http://www.raspberrypi-spy.co.uk/2012/08/reading-analogue-sensors-with-one-gpio-pin/)).
+* Output ports can be set **conditionally** on values of input ports (i.e. darknessSensor1in==1&lamp1out=1, see cron.conf).
+* You can give each port a custom name to make your client more understandable.
+* You can define a default state on GPIO output ports.
+* You can define a blocking time for a GPIO output port (so it is not switched to
   fast in case the user makes a request twice).
-* You can define a toggle time for an output port (i.e. if you want to turn
+* You can define a toggle time for a GPIO output port (i.e. if you want to turn
   a port on for a defined period of time, it can be done with a single request). 
-* You can set a simulation mode for testing your client.
+* You can set a **simulation mode** on GPIO ports for testing your client.
 * Controlling multiple ports in one requests are set one after another, but the code
   is optimized and nothing unnecessary is done in between (it takes about 2-5ms on an idle Raspberry Pi to set all 17 ports, some artificial load (e.g.'find /' in the background) will slow it down to 10-15ms).
-* Cronjobs (exact to the second) for output ports are based on [quartz-scheduler.org](http://quartz-scheduler.org/documentation/quartz-2.1.x/tutorials/crontrigger). Output ports can be set conditionally and you have a simple but powerful semaphore mechanism.
-* You may define your own variables with a prefix VIRTUAL which are persisted in memory (unknown virtual variables default to "0").
+* **Cronjobs** (exact to the second) for output ports are based on [quartz-scheduler.org](http://quartz-scheduler.org/documentation/quartz-2.1.x/tutorials/crontrigger). Output ports can be set conditionally and you have a simple but powerful semaphore mechanism.
+* You may define your own variables with a prefix VIRTUAL which are persisted in memory (unknown virtual variables default to "0"). This is helpful to keep track of the state for toggling output ports.
+* You can integrate any **script** into the command chain in order to have a greater power. External scripts (or commands) must be prefixed with CMD (i.e. to handle other hardware like SPI, I2C or UART or to send notifications via e-mail or push notifications).
 
 ### Planned Features
 
-* Custom hooks (pre/post), e.g. for notifications
 * More status and configuration information requestable via json (disengageable)
 
 ### Possible Unplaned Features
 
 * Bit sequences (especially with AUTO.TOGGLE.TIME) for serial output or to control a servo (probably an SPI interface)
 * Some kind of PLC (Programmable Logic Controller)
+* GPIO input state change notification (instead of polling)
 * Suggestions are welcome
 
 
 ## Project Status
 
-The project has started and I use it by myself mainly for
-simple output (manually and with cronjobs). If I had to give it a release number, I would say it is a 0.85 release. Bug reports and feature requests are welcome.
+The project has started in summer 2012 and I use it by myself mainly for simple output (manually and with cronjobs). If I had to give it a release number, I would say it is a 0.88 release. Bug reports and feature requests are welcome.
 
 
-## Getting Started (from tgz)
+## Getting Started (from tgz) - not recommended!
 
 1. [Download](https://bitbucket.org/sbub/raspberry-pi-gpio-web-control/downloads) the latest version of the package as raspberry-pi-gpio-web-control-[version].tgz
 
 
 ## Going Productive
 
-* Make sure you **disable simulate mode**.
+* Make sure you **disable simulate mode** in gpio.conf set `simulate.gpios=false`.
 * Turn down logging after testing in log4j.properties (this is important for performance on your Raspberry Pi).
 * A simple init.d script is also provided in file src/main/resources/init.d/gpio-winstone which can be installed with the follwing commands:
 
 * `out1=1&in1==1&out2=1&analogTI=IN&out3=1` (given in1==1 is true) is handled  internally as `out1=1&in1==1&analogTI=IN&out2=1&out3=1`
 
 
+## External commands/scripts
+
+You can integrate any external command or script into the servers command chain. Configuration is done in `cmd.conf`. More information is descripted there, too. Make sure that the command/script is either full qualified and absolute (i.e. /full/qualified/path/and/file) or it has to be reachable via your PATH variable (keep in mind that the init.d-script may have different environment settings). You can not call every command via http (or automatically via cron), but only those, you have specified. You have to give your script a name to be addressed. This name must be prefixed with CMD (i.e. EXTCMD.NAME.1=date must be addressed `CMDdate=1`). You must call your script with a parameter (or in other words with a value within the GET-parameters), but your script does not have to act on it if you don't need it.
+
+This feature is a  generic implementation of my previous planned featue named "custom hooks" (pre/post) as it gives you full power to integrate anything (i.e. handle other hardware like SPI, I2C or UART or to send notifications via e-mail or push notifications).
+
+### Example of an alarm system
+
+The following configuration is given:
+
+You have a script which send notifications (i.e. email or sms or iPhone push notifications):
+
+```
+EXTCMD.NAME.1=notify
+EXTCMD.COMMANDNAME.1=/path/to/my/script.sh
+EXTCMD.TIMEOUT.1=5000
+```
+
+* You have a GPIO input port which is connected to a door-is-open-sensor named `doorIsOpenIN`.
+* Between 09:00 and 20:00 you want to be notified if the door is open. You have one cronjob:
+
+```
+#check door between 9:00 and 19:59 and notify if it is open 
+0 * 9-19 ? * * :: doorIsOpenIN=IN&doorIsOpenIN==1&CMDnotify=1
+```
+
+
 ## Copyright
 
 Copyright 2012  der-bub.de
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.