Customizing the Gecko OS Web App
The Gecko OS Web App demonstrates the full capability of the Gecko OS HTTP RESTful API. See Gecko OS Web App . The layout and operation of the web app can be 100% customized to suit your application and your business.
The following simple examples show how to re-style the original Gecko OS styling to match the style of another brand.
If this layout or style does not suit your requirements, the entire web application can be replaced simply by modifying the root file of the Gecko OS webserver with http.server.root_filename .
The Web App Development System
The Web App development system provides a rapid edit-build-test cycle, using a local Web server on the development test machine.
The diagrams below show how the Web App development system works, and how it differs from the Web App production system.
In the development system, the test HTTP server serves the Web App from the development file system, and requires CORS to make REST requests to the Gecko OS HTTP server , in order to run Gecko OS commands.
The Web App Production System
In the production system, the Gecko OS HTTP server serves the Web App from the Gecko OS device file system, and REST requests to the Gecko OS device are made to the same origin.
Set Up and Prerequisites
Obtain a copy of the Gecko OS Web App development system from https://github.com/SiliconLabs/gecko-os-webapp
In the following it is assumed that your working copy is in the directory
/gecko-os-webapp
.
Web App Languages and Libraries
The Gecko OS Web App development system uses Pug templates and the Less CSS pre-processing language.
For more information on Pug templates, see https://pugjs.org .
You can, if you prefer, use traditional HTML and CSS for development. See the /gecko-os-webapp/README.md file for details.
The Gecko OS Web App uses the following JavaScript libraries:
- Backbone.js - Web App development framework - MV* (Models Views etc)
- jQuery - backbone dependency - DOM management
- Underscore - backbone dependency - js utility functions
- Async.js - handles synchronous and asynchronous tasks - allows Gecko OS commands to run synchronously
- Gecko OS JavaScript API - Framework for controlling a Gecko OS device using the HTTP RESTful API
The style modifications described in this tutorial can be made without detailed knowledge of JavaScript, CSS or Pug.
However to make advanced modifications to the Gecko OS Web App, familiarity with these languages and frameworks is recommended.
Setting up the Gecko OS Web App Development Environment
The Gecko OS WebApp development system uses Node.js , Grunt and Bower for package management and build automation. These tools are free.
To set up the Gecko OS Web App development system, follow the /gecko-os-webapp/README.md instructions, available on github and in the top level directory of the working copy.
This involves downloading and installing
Node.js
, then using the node package manager,
npm
, to install
Bower
(front end package manager) and
Grunt
(task runner). Then run
npm install
and
bower install
from a command prompt in the
/gecko-os-webapp
directory.
Setting up the Gecko OS device
The Web App development system runs a server at
http://localhost:5002
, on the machine on which the build system is running.
The Web App development system communicates with a Gecko OS device on the same network. The module needs to run the HTTP server, and Cross Origin Resource Sharing (CORS) must be enabled for the development host domain. The simplest way is to enable CORS for all domains.
Open a Gecko OS Terminal and issue the following Gecko OS command sequence on the device:
Gecko OS Commands | Description |
---|---|
|
|
After rebooting, the module Gecko OS terminal displays output similar to:
[Ready]
SILABS-WGM160P-4.0.0, Gecko_OS-STANDARD-4.0.12-1198, WGM160P
[Associating to My_Network]
> Security type from probe: WPA2-AES
Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.55
Starting mDNS
mDNS domain: mymodule.local
HTTP and REST API server listening on port: 80
[Associated]
Configuring the Module and Development Host Addresses
The Web App development system needs the IP address or name of both the Gecko OS device and the development host.
The Gecko OS device address allows the HTTP RESTful API calls to the module from the development host Web server test Web App.
The development host address allows deployment of the changed web app files to the module from the localhost development Web server.
Open the file
/gecko-os-webapp/config.json
and set the addresses. For example:
{
"device": "mymodule",
"localIP": "10.5.6.60",
"port": "5002"
}
You can also change the development Web server port if desired.
Building the Web App and Running the Test Server
To build the Web App, at a command prompt, in the
/gecko-os-webapp
directory, issue the command:
grunt
Grunt runs tasks and displays output accordingly, similar to:
Running "build:dev" (build) task
Running "embed-hash" task
Running "jshint:gui" (jshint) task
>> 17 files lint free.
Running "buildCopy:dev" (buildCopy) task
Running "string-replace:dev" (string-replace) task
1 files created
Running "uglify:build" (uglify) task
File out/webapp/gecko-os.js created: 400.26 kB → 236.25 kB
File public/views/js/recovery.min.js created: 9 kB → 5.59 kB
File public/views/js/index.min.js created: 1 kB → 821 B
>> 3 files created.
Running "string-replace:release" (string-replace) task
2 files created
Running "less:build" (less) task
>> 3 stylesheets created.
Running "pug:build" (pug) task
>> 4 files created.
Running "compress:build" (compress) task
>> Compressed 2 files.
Running "buildCleanup:dev" (buildCleanup) task
Running "writeVersion" task
Running "server" task
Web server running at http://localhost:5002
The "server" task continues until you halt it. While it is running you can view the test Web App Page.
To halt the "server" task and grunt execution, type
Ctrl-C
.
Opening the Test Web App Page
While the "server" task is running, in a web browser, open
http://localhost:5002
.
Changing the Logo
The Silicon Labs logo appears at the top left corner of the Gecko OS Web App. You can change this to a logo of your choice.
The logo is specified in the file
/gecko-os-webapp/public/less/logo.less/
.
It is set up as a background image for the
.logo
css class.
The first lines of the
logo.less
file are as follows:
.logo {
height: 137px;
background-image: url("data:image/svg+xml;...
...
In the unmodified
logo.less
file partially shown above, the logo image is created with an inline svg file specified with a data url.
Logo Image File
To substitute your own logo image, in
logo.less
, you can use:
background-image: url('logo.png');
and comment out the line that begins:
background-image: url('data:image/svg+xml;
Place your own logo image file in the directory
/WebApp/out/webapp/
. Stylesheet relative URLs are determined relative to the
/out/webapp/gecko-os.css
file, which is the product created from the various
/WebApp/public/less/*.less/
files during the build process.
Replace the filename 'logo.png' with the name of your substitute logo file. For example:
background-image: url('sdc_logo.png');
Logo Dimensions and Aspect Ratio
The logo dimensions are by default:
height:100px; width:280px;
Create a logo of the specified proportions to fit into the available space, or modify the dimensions in the
logo.less
file if you prefer.
If your logo has a different aspect ratio, you can leave the width of 280px unchanged and calculate a new height as follows:
new_height = my_logo_height*(my_logo_width/280)
Set the new height in the
logo.less
.logo class height parameter. For example,
.logo {
height: 69px;
...
}
Logo Background Color
You can change the logo background-color parameter in the
logo.less
.logo class.
To allow the background of the navigation pane (div.nav element) to show through, remove the background-color style setting. For example:
.logo {
height: 69px;
...
//background-color: #333;
...
}
To see the results of any change, rebuild the web app: stop the "server" task and
grunt
if it is running (
Ctrl-C
) and run
grunt
again. Then refresh the Web App page in your web browser.
Changing the Logo Link
The link from the logo is specified in the Pug template for the index.html file,
/gecko-os-webapp/public/views/index.pug
Open the
index.pug
file and locate the following lines:
body
div.nav
a.wlan(href="//www.silabs.com", data-bypass, target="_blank")
div.logo
To change the logo link, change the
href
attribute value. For example:
...
a.wlan(href="//sensors.com", data-bypass, target="_blank")
...
Pug templates determine structure from indentation, so be careful not to alter the indentation.
To see the change, run
grunt
to rebuild the Web App, and refresh the Test Web App page.
For more information on Pug templates, see https://pugjs.org .
Changing Styles
The styles of the Gecko OS Web App are determined by
/gecko-os-webapp/out/webapp/gecko-os.css
. This is built from the
/gecko-os-webapp/public/less/
files.
To change styles, first identify the css class to be altered. You can use your web browser developer tools to identify css classes associated with elements.
Then modify the
*.less
file that defines the css class definition.
For example, the navigation menu background (div.nav element) is determined by the
.nav
css class, which is defined in
app.less
.
.nav {
...
.gradient(@nav-light, @nav-dark);
...
}
The Less variables
@nav-light
and
@nav-dark
are defined in
variables.less
, included at the top of the
app.less
file:
@import "variables.less";
In
variables.less
, change the variables as desired, e.g.
//@nav-light: #3e3c3d;
@nav-light: #0db8d3;
//@nav-dark: #2d2c2d;
@nav-dark: #0881b6;
The highlights and shadows of the menu items are also set in
variables.less
as
@nav-highlight
and
@nav-shadow
. You can define a Less variable to have the value of another defined Less variable. For example:
//@nav-highlight: @dark;
@nav-highlight: @nav-dark;
//@nav-shadow: @darkest;
@nav-shadow: @nav-light;
To see the change, run
grunt
to rebuild the Web App, and refresh the Test Web App page.
Changing Features
Each Gecko OS Web App feature corresponds to a Backbone.js view.
Each view corresponds to a menu item in the main navigation menu, defined in
app.js
, and to a JavaScript view definition file in the
/gecko-os-webapp/public/js/views
folder.
For example, the "Cloud Services" menu item corresponds to the 'cloud' element in the
app.js
definition of the
appViews
array:
var appViews = [
...
{el: 'cloud', nav: 'Cloud Services', view: App.Views.Cloud, modes: ['wlan']}
...
]
The "Cloud Services" feature is also supported by the view definition file
/gecko-os-webapp/public/js/views/cloud.js
.
Removing a Feature
To remove a feature, delete the corresponding
appViews
array element and the corresponding JavaScript view definition file.
For example, to remove the "Cloud Services" feature:
-
delete the ''
array item in the
app.js
Be sure to maintain the JavaScript array syntax: elements are comma-separated and there is no comma after the final element. -
delete the
/gecko-os-webapp/public/js/views/cloud.js
file.
To see the change, run
grunt
to rebuild the Web App, and refresh the Test Web App page.
Adding a Feature
To add a feature, add a corresponding element to the
appViews
array, and add a view to the
/gecko-os-webapp/public/js/views/
folder.
For example, to add a simple page called "My Feature", add the following element to the
appViews
array:
{el: 'myfeature', nav: 'My Feature', view: App.Views.MyFeature, modes: ['wlan']},
Ensure that the array syntax is maintained correctly.
The parameters are as follows:
-
el
: DOM element id, used in the view definition -
nav
: the title as it appears in the navigation menu -
view
: the Backbone.js View object - must match the object defined in the view definition -
modes
: lists the Gecko OS Web App modes for which the element is displayed:-
setup
(Setup mode) -
softap
(Local mode) -
wlan
(Internet mode)
-
Download the
myfeature.js
file and add it to the
/gecko-os-webapp/public/js/views/
folder. This is a minimal view that displays some text.
To see the change, run
grunt
to rebuild the Web App, and refresh the Test Web App page.
Deploying the Modified Web App to the Gecko OS device
Ensure that the module and development host addresses are correctly configured. See Configuring the Module and Development Host Addresses above.
Ensure that the grunt "server" task is running the development test Web server. To do this, run
grunt
at the command prompt.
At a separate command prompt, run:
grunt deploy
In the background, the Web App development system runs the http_download command, on the Gecko OS device, to download files from the development Web server to the module.
You may also need to download other files, such as your logo file. You can do this in a Gecko OS Terminal on the module, using the
http_download
command. The files must be in the
/gecko-os-webapp/out/
folder. For example, if the development host IP address is
10.5.6.60
:
hdo http://10.5.6.60:5002/webapp/sdc_logo.png webapp/sdc_logo.png
When deployment is complete, you can open the modified Web App directly from the module. For example, if mDNS is used as described above, open:
http://mymodule.local
The Web App operates as shown in the Web App Production System diagram in The Web App Development System above.
Deploying the Web App in a Native API App or Other Bundle
When deploying a Web App in a Native API App, or in any bundled app, the webapp files must be included in the bundle's
manifest.json
file. This ensures the webapp files are included when the application is updated.
Supporting Gecko OS Versions
- Gecko OS 4
Change Log
Modified | Changes |
---|---|
2019-01-01 | Created |
2019-03-15 | Use Silicon Labs repo |