[[!meta title="Webconverger API documentation"]]
Webconverger heavily uses the notion of /proc/cmdline
to control setup.
Spaces in cmdline
values
need to be encodeURI
in order not be considered keys themselves. For
developers, [[startup]] might better explain how these are used.
There are two ways to start using the API, firstly by hitting TAB on the boot screen. See [[testing]] for a video of how to do this in a Virtual machine.
Or by using the configuration service form which you need to take a subscription out with Webconverger. The service presents the various options below in a friendly Web form on boot, which are saved on the Web so your values are retained between boots once subscribed.
Edit homepage=
You can enter several homepages, which will open in several tabs, separate each
address with %20
e.g.
homepage=http://portal.webconverger.com/%20http://webconverger.com
- MACID expands to your network MAC address
- USBID expands to USB serial, for identifying which USB stick was booted - you could conceivably use different USB sticks for a lightweight (but not secure) physical authentication,
USBID_override=
is a way to override this value. - WEBCID expands to Webconverger's identifier
- WEBCVERSION expands to use
git describe
the running instance's version
For example: Customers want to track which kiosks are logging in. These is best accomplished using a keyword MACID. For example the homepage:
homepage=http://webconverger.com/?mac=MACID
Could be expanded to
homepage=http://webconverger.com/?mac=081196ae2d3c
Using instantupdate
from version 28.
This video has an instantupdate demonstration. Good for getting a pool of Webconverger devices on the same page. Support by the [[rpi2]] & x86 version currently. Android coming soon.
https://github.com/Webconverger/webc/tree/master/etc/webc/extensions
- chrome=webconverger - this is the default
- chrome=webcnoaddressbar - disable URL bar and search bar, good for [[controlled_access_setups|filtering]]
- chrome=webcfullscreen - fullscreen without any chrome
- chrome=neon - fullscreen as used with Neon
- chrome=debug - nightly testing tools, for [[testing]] crash recovery etc. and to expose
about:config
See [[kiosk]] for screenshots of the options.
Neon configuration example (a complex example)
chrome=neon
homepage=http://iframereload.dabase.com//?mac=MACID
timezone=Asia/Singapore
cron=00%2003%20*%20*%20*%20root%20killall%20firefox
hidecursor
noblank
xrandr-all=--rotate%20left
Explanation of the above:
- Set the chrome (not the browser, but the GUI), to a dark themed "neon" for <abbr="Digital Out Of Home">DOOH
- Set the homepage to http://iframereload.dabase.com/, whilst also passing a screen identifier (mac address)
- Set the timezone to Singapore, so we can express a local time in the next line
- [[Schedule a job|cronjob]] to run at 3AM, to kill firefox, the browser used in Webconverger. This is to ensure responsiveness in case there is a memory leak
hidecursor
makes sure the mouse cursor is invisiblenoblank
ensures the screen does not turn black, i.e. it's always showing the rendered Web page- Rotate connected screens to portrait
Please see [[filtering]] page.
Please refer to [[i18n]]
Please see [[artwork]] for details how to use bgurl=
append http_proxy=http://192.168.1.5:8888
NEW in version 26: Basic authentication http_proxy=http://user:pass@proxy:3128
Append noblank
, see [[blanking]] for more.
Use kioskresetstation
, see [[blanking]] for more information
Add noclean
. This is not recommended for deployments, however if some
cases where the machine is used by just one person, this is very convenient for
day to day usage.
To rotate right on all connected screens:
xrandr-all=--rotate%20right
This is computed as running xrandr --output CONNECTED_DEVICE --rotate right
.
For finer control by explicitly naming your CONNECTED_DEVICE, you can use
xrandr=
, but then you must discover the exact name of your output device,
which can vary machine to machine.
Video explaining how to use debug mode to discover the properties of your connected displays
Please follow this [[display]] guide.
Append debug
.
Once Webconverger is booted, the dwm window
manager defaults to shift+alt+enter for a
Terminal. Gain root with sudo -i
.
Please see [[debug]] for more.
swarp=0,0
Moves the mouse cursor to the top left of the screen. This is useful when the default cursor in the middle of the screen might accidentally trigger some mouse over event in the Web application.
Append noupgrade
. See [[upgrade]] for more details.
Append noconfig
Set a [[cronjob]]
Please refer to [[networking]]
Use noescape
, which disallows [[debugging|debug]] of installed Webconverger.
However it only kicks in after the boot configuration is rewritten after a
successful upgrade.
Hiding the cursor is often used with touch screens:
hidecursor
Caveat: Since hidecursor can only be applied when starting X, you cannot use this option in the Live mode with the configuration service.
Showing:
showcursor
By default the cursor is shown on input use and hides after 5 seconds. See [[blanking]] for details.
Please see screensaver.
Please refer to the [[touch_screen_calibration]] wiki page for calibration and UI tweaks like widescrollbars
and grabdrag
.
Using the printer=
API, documented in [[printing]].
showprintbutton
Use numlock
.
prefs=
sets Firefox's powerful autoadmin.global_config_url
autoconfig
feature.
Examples:
- prefs=http://prefs.webconverger.com/2015/safe.js - force Google to provide a safe search result
- prefs=http://prefs.webconverger.com/2015/chromebook.js - override user agent string
- prefs=http://prefs.webconverger.com/2015/click-to-play.js - Opt into [[flash|adobe]]
- prefs=http://prefs.webconverger.com/2015/disable-safebrowsing.js - Disable Google's safe browsing
Please look for further usage examples in [[printing]] and [[allowing_popups|blog/entry/Popups_and_SSL_warnings]].
Stanza for you to indicate your current email address, so we can contact you in the case your configuration id becomes unclear.
Ignored by Webconverger OS itself.
Sign up for an account with Papertrail
log=logs.papertrailapp.com:XXXXX
Replace XXXXX with the port number associated with your account.
Alternatively, you can use the support
command to send us your logs to the
http://support.webconverger.com/ service available from the information
icon next to your alias in the configuration panel.
Although wired connections are preferred, Webconverger does have comprehensive [[support_for_wireless_devices|wireless]] and [[blog/entry/USB_tethering]].
tabswitch=5
Switch between tabs on chrome={neon,webcfullscreen} every 5 seconds.
Screencast: http://youtu.be/eh6u6Bmjnu8
Please see [[artwork]].
Add to your configuration:
hidecursor
We do set volume to 100% by default however sometimes it might need tweaking, for example:
amixer=sset%20Master%20100%25
We have an interface on synclient
synclient=TapButton1%3D1
New from June 2016, for example:
opensearch=http://prefs.webconverger.com/bl.xml
Only applicable with default chrome=webconverger
, since that [[user_interface|kiosk]] has a URL bar for entering search terms.