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:

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 

set wlan.ssid               <NETWORK NAME>
set wlan.passkey            <NETWORK PASSWORD>
set wlan.auto_join.enabled  1
set http.server.enabled     1
set mdns.name               mymodule
set mdns.enabled            1
set http.server.cors_origin *
save
reboot


Set your Wi-Fi network name
Set your Wi-Fi network password
Enable WLAN auto join
Enable HTTP server
Set mDNS name
Enable mDNS
Enable CORS for all
Save
Reboot

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 .

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.

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:

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:

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

Change Log

Modified Changes
2019-01-01 Created
2019-03-15 Use Silicon Labs repo