-
Notifications
You must be signed in to change notification settings - Fork 74
WPEFramework
WPEFramework is a small framework built for embedded devices. It consists out of the following main components:
- Framework Core
- Framework Plugins
- Framework UI
The framework core provides a internal RPC, Web API and controller to launch plugins. It comes with a lot of built in tooling such as json parsers, websocket and webapi capabilities. It is designed to launch plugins in a specific order with inter-plugin dependencies. All asynchronously and with advanced communication between the plugins.
The Framework Plugins are open source publicly available plugins to be used with WPEFramework and the Framework User Interface provides an interface to externally manage/develop on a device running WPEFramework. It provides an UI to launch/stop plugins and interact with individual plugins that have been implemented in the user interface. To access it simply open the URL of the device (port 80) with any browser you have.
The simple use case is for WPEFramework to the plugin that instantiates the browser. After it has been instantiated the WPE WebKit can be controlled through the WebAPIs from WPE Framework. Such as setting the URL, getting the current FPS and read information on its memory consumption.
A more complex usecase is the following: WPEFramework comes up and immediately starts a webserver and other basic plugins such as device info and monitor. WPEFramework detects the graphics driver is ready and launches the browser, pointing to a local URL for immediate rendering while configuring the network (network plugin). Once the network has been established it will set the time and optionally location of the device. Followed by launching the DRM (OpenCDM) module. All while sending the async events through the WebSocket so that the initial local app that was loaded in the browser knows the system is ready to access the internet, has valid time and location so it can decrypt DRM protected content.
With the last usecase we have an RPI3 booting and showing graphics in less then 15 seconds, ready to play content in around 20 seconds.
WPEFramework is built from this repo and is open source. It contains all the basic tooling to run WPEFramework and libraries required within the framework.
WPEFramework Plugins is built from here and contains all the open source plugins that run inside the framework. Such as:
- Bluetooth support
- Device Info to expose device metrics
- Location sync for a geolocation service
- Monitor to monitor processes and restart them on failure or exceeding memory usage
- OpenCDMi for the OpenCDM server to be used with WPEWebKit and OCDMi modules
- Remote Control for remote control, such as virtual remote
- Snapshot takes a snapshot from the HDMI output and returns it
- Time sync synchronises ntp time
- Tracing provides a logging mechanism for anything running in WPEFramework
- UX A WebGL optimized tab of WPEWebKit (same as Webkit Browser)
- WebKit browswer launches and manages the WPEWebKit browser
- WebServer tiny webserver
- WebShell A remote SSH alike interface to access the device shell through webapis
- WiFi a plugin to manage the WPA supplicant wifi capabilities
- YouTube a YouTube optimized tab of WPEWebKit (same as WebKit Browser)
Note that WPEFramework allows for additional plugins to be created outside the above repositories. This provides that ability for anyone to write their own WPEFramework plugin and pull it in from their own source (public or not). As long as the .so is placed in the right directory and the configuration JSON file is present WPEFramework will detect it and provide capabilities to launch/manage it.
The WPEFramework API comes in two parts:
- WebAPI (HTTP GET/POST/PUT/DELETE)
- WebSockets (async)
Typically all commands provided to the framework are provided through the webapi and asynchronous events back to the client from the framework are done via the websocket interface.
Each plugin provides its own definition of the WPEFramework "micro services". That means that individual plugins can extend the API based on the needs of the plugin.
By default the interface is available on port :80 and starts with /Service. The template is as follows:
<METHOD> http://<ip>:<port>/Service/<Plugin>/<action>
Where:
-
Method (REST-like):
- GET Retrieves information
- PUT Updates information
- POST Creates information
- DELETE Deletes information
- IP is the ip of your embedded device
- Port is the port where WPEFramework is configured to run (default is port 80)
- Plugin is the plugin name you are interacting with
- Action is the plugin specific action/path you are going to interact with
Note: To use curl you can use -X <method>. For example:
curl -X PUT http://127.0.0.1:80/Service/Controller/Activate/WebKitBrowser/
Activates the browser
The only non-deleteable Plugin is the Controller plugin. The controller plugin is built into the core of WPEFramework as it wouldn't work without it. The Controller API is simple, it has two main functions: provide information on the available plugins as the controller knows them and provide an interface to start/stop plugins.
Template
GET http://<ip>:<port>/Service/Controller
Returns a list of plugins and their information. Which is too large to paste into this tutorial, but here is a snippit:
{
"plugins":[
{
"callsign":"Controller",
"classname":"Controller",
"configuration":{
"subsystems":["Location","Time","Internet"],
"resumes":["WebKitBrowser","WebServer"]
},
"state":"activated",
"processedrequests":1,
"processedobjects":0,
"observers":0
},
{
"callsign":"DeviceInfo",
"locator":"libWPEFrameworkDeviceInfo.so",
"classname":"DeviceInfo",
"state":"activated",
"processedrequests":0,
"processedobjects":0,
"observers":0,
"module":"Plugin_DeviceInfo",
"hash":"3533cd0d2e8fdc080bd55e366c31590dfc385659"
}
],
"server":{
"threads":[4,5,4,3,3,3],
"pending":0,
"occupation":0
}
}
Template:
PUT http://<ip>:<port>/Service/Controller/<action>/<plugin>
Where:
-
Action can be
ActivateorDeactivate - Plugin is the plugin callsign
For example to launch the webkit browser:
PUT http://127.0.0.1/Service/Controller/Activate/WebKitBrowser
And to stop the webkit browser:
PUT http://127.0.0.1/Service/Controller/Deactivate/WebKitBrowser
Asynchronous notifications are provided through a WebSocket interface. The WebSocket can be opened towards the controller on the following URL:
ws://127.0.0.1/Service/Controller/Notification
Once the websocket is setup you'll receive JSON messages that depict the status of the changes on WPEFramework.
For example:
{"callsign":"WebKitBrowser","state":"deactivated","reason":"Requested"}
If the WebKitBrowser gets deactivated.
A default build comes with the WPEFramework User Interface that is pulled from this repo. The user interface provides a web based interface to control the WPEFramework and its plugins.
Simply open the default webserver on your embedded device by pointing your browser of choice to:
http://<ip of your device>/
And you should get an user interface that allows you to stop/start plugins and interact with each plugin that has an UI.
There are a few nifty features:
- Any key pressed within the UI will automatically be forwarded to the default (note: requires virtual remote to be enabled)
- It will automatically reconnect if you reboot the device
- Allows you to see snapshots straight from the UI (useful for remote debugging)
The WPEFramework and each Plugin generates a json based configuration file that is stored in
/etc/WPEFramework
Each plugin has its own configuration file in:
/etc/WPEFramework/plugin/<pluginname>
For example for the WebKitBrowser plugin the configuration looks like this:
{
"locator":"libWPEFrameworkWebKitBrowser.so",
"classname":"WebKitBrowser",
"precondition":[
"Graphics",
"WebSource"
],
"autostart":true,
"configuration":{
"url":"http://127.0.0.1:8080",
"useragent":"Mozilla/5.0 (Macintosh, Intel Mac OS X 10_11_4) AppleWebKit/602.1.28+ (KHTML, like Gecko) Version/9.1 Safari/601.5.17 WPE-Reference",
"injectedbundle":"libWPEInjectedBundle.so",
"transparent":false,
"compositor":"noaa",
"inspector":"0.0.0.0:9998",
"fps":true,
"cursor":false,
"touch":false,
"msebuffers":"audio:2m,video:15m,text:1m",
"memoryprofile":"128m",
"memorypressure":"databaseprocess:50m,networkprocess:80m,webprocess:250m,rpcprocess:80m",
"mediadiskcache":false,
"diskcache":"512m",
"xhrcache":true
}
}
Do not change the stuff above the configuration tag, unless you know what you are doing. But there are a few usefull values we should cover here.
`url` Sets the default URL to be launched when starting WPE WebKit
`useragent` Sets the user agent to be used within WPE WebKit
`injectedbundle` Sets the .so injected bundle to be loaded when starting WPE WebKit
`transparent` Switches the default WebKit background to be transparent or not
`compositor` Is by default set to NOAA to turn off AA in Cairo
`inspector` The default binding address for the WebInspector
`fps` Turns on the FPS counter with WebKit (allows you to retrieve FPS count on the webAPI)
`touch` Enables RPI touch features in WebKit
`msebuffers` Configures the MSE playback buffers
`memoryprofile` Sets the desired WebKit memory profile to run on
`memorypressure` Sets the WebKit memory limits
`mediadiskcacke` Enables the disk caching for media playback
`diskcache` Sets the limit of the disk cache
`xhrcache` Enables the XHR request caching
Note some values of the WebKit configuration can also be set at built time, for example for the default start url: https://github.com/WebPlatformForEmbedded/meta-wpe/blob/master/recipes-wpe/wpeframework/wpeframework-plugins_git.bb#L16-L24
Additional documentation can be found in the WPEFramework and WPEFramework Plugins repositories. For documentation on the main WPEFramework please see:
https://github.com/WebPlatformForEmbedded/WPEFramework/tree/master/doc
For information on the plugin, each plugin comes with its own document placed under <PluginName>/doc. For example for the WebKitBrowser Plugin documentation:
https://github.com/WebPlatformForEmbedded/WPEFrameworkPlugins/tree/master/WebKitBrowser/doc
Yes, I know. They're MS Doc based, hopefully we will change them to markdown soon.