AN1023: HTTP SERVER EXAMPLE
APPLICATION NOTE
Tuesday, 22 September 2015
Version 1.0
Silicon Labs
Page 2 of 18
Contents
1 Introduction ..........................................................................................................................................................3
Figure 1 - http_serv Project Structure ..................................................................................................................3
3 BGScript Files ........................................................................................................................................................5
3.1
Overview .......................................................................................................................................................5
3.2
api.bgs ...........................................................................................................................................................5
Figure 3 - Resource URL's .....................................................................................................................................5
Figure 5 - api_handle_ap_settings_request() ......................................................................................................6
Figure 6 - api_handle_ap_settings_request() cont. .............................................................................................6
Figure 7 - ap_init_mode .......................................................................................................................................7
Figure 8 - ap_start_mode() ...................................................................................................................................7
Figure 9 - ap_start_mode() cont. ..........................................................................................................................8
Figure 10 - ap_start_mode() cont.........................................................................................................................9
Figure 11 - sme_ap_mode_started() ....................................................................................................................9
Figure 12 - https paths ..........................................................................................................................................9
Figure 13 - sta_init_mode() ............................................................................................................................... 10
Figure 14 - sta_start_mode() ............................................................................................................................. 10
Figure 16 - Imported Files .................................................................................................................................. 11
Figure 17 - system_boot() ................................................................................................................................. 11
Figure 18 - sme_wifi_is_on() ............................................................................................................................. 11
4 HTML Files ......................................................................................................................................................... 13
4.1
index.html .................................................................................................................................................. 13
Figure - index.html............................................................................................................................................. 13
Figure - doGetStatus() ....................................................................................................................................... 13
4.2
ap.html ...................................................................................................................................................... 14
Figure - ap.html ................................................................................................................................................. 14
Figure - doApply() .............................................................................................................................................. 14
Figure - doStoreSettings() .................................................................................................................................. 15
4.3
sta.html ...................................................................................................................................................... 15
Figure - sta.html ................................................................................................................................................. 15
Figure - doGetNetworks() .................................................................................................................................. 16
Figure - doApply() .............................................................................................................................................. 16
Figure - doStoreSettings() .................................................................................................................................. 16
Silicon Labs
Page 3 of 18
1 Introduction
The http_serv example included with latest SDK, wf121-1.3.0, demonstrates how the WF121 can be configured
to operate in Wi-Fi Access Point mode, Wi-Fi Client mode, and additionally implements HTTP server
functionality allowing the Wi-Fi Access point settings to be configured and also the Wi-Fi module to be re-
configured to operate in Wi-Fi Client Mode and connect to an available Wi-Fi network via HTML pages
displayed by the server. This application note breaks down the http_serv example into its' respective
components so that each can be described in a functional sense individually.
The BGScript source files included in the project are responsible for the application logic including HTTP server
functionality, Wi-Fi Access Point mode operation, and Wi-Fi Client Mode operation. The HTML source files
provide the medium for application related content and/or data to be displayed and interacted with. This
application note will begin with a discussion of the http_serv examples' project and hardware configuration
followed by a detailed discussion of the application logic provided by each of the BGScript source files and then
an explanation of how application content is transferred between the BGScript application and each of the
HTML pages.
Figure 1 - http_serv Project Structure
Silicon Labs
Page 4 of 18
2 Project and Hardware Configuration
The project and hardware configuration settings for the http_serv example are set in the project.xml file included
in the main project folder. The project configuration is broken apart into 3 part, a top level defined by the
<project> tag and two sub levels defined by the <hardware> and <files> tags.
Within the top level <project> tag, the script to use is defined within the <scripting> tag. The hardware
configuration is contained within the <hardware> tags. UART channel 0 is configured for application use by
setting the api property to false, with a baud rate of 5000000bps and flow control enabled by setting handshake
to true. UART channel 1 is configured for API use with a baud rate of 5000000bps and flow control enabled.
The <files> tag is used to define the individual files such as HTML pages which will be included in the compiled
firmware.
Silicon Labs
Page 5 of 18
3 BGScript Files
3.1
Overview
The http_serv example includes 4 individual BGScript source files, main.bgs, api.bgs, ap.bgs and sta.bgs. Each
of the files implements a specific type of functionality and are all imported into the main.bgs file which comprises
the application logic as a whole. The ap.bgs and sta.bgs files contain the Access Point and Station mode
functionality respectively. The RESTful API used by the web pages to exchange application data with the
BGScript application is implemented in the api.bgs source file. This portion of the App Note will provide an
overview of each of the BGScript source files covering the important events and procedures in detail.
3.2
api.bgs
The api.bgs BGScript file comprises the RESTful API functionality/logic used by the HTML pages to exchange
data with the BGScript application. The api.bgs BGScript source file contains a relatively large number of
custom procedures defined written to aid in building JSON formatted responses to HTTP requests received by
HTTP server and are called frequently. It would be a good idea to look through the procedures to see what they
do so that you understand why they are called in other portions of the script.
When an HTTP request is received from one of the HTML pages, the https_api_request event is triggered
providing the request number, the HTTP request method (PUT, POST, GET, ....), and the resource data. The
resource data is then compared with the predefined resources listed as "const" towards the beginning of the api.
bgs source file.
Figure 3 - Resource URL's
Silicon Labs
Page 6 of 18
Figure 4 - https_api_request
When a match is found between the resource data included with the http request and one of the predefined
resource URL's, a procedure written to handle the matching request is called. For example, when the received
request is found to match the API_AP_SETTINGS_RESOURCE, the api_handle_ap_settings_request
procedure is called. The api_handle_ap_settings_request procedure builds a JSON formatted response
containing the Access Point settings to return as the response to the HTTP request.
Figure 5 - api_handle_ap_settings_request()
After the response has been constructed it is sent using the https_api_response API method followed by
completing the response with the https_api_response_finish. It's important to note that the "request" number
referenced here corresponds to the original "request" number received with the https_api_request event.
Figure 6 - api_handle_ap_settings_request() cont.
Silicon Labs
Page 7 of 18
3.3
ap.bgs
The ap.bgs BGScript file implements the Access Point functionality of the http_serv example project. The
ap_init_mode procedure is called from within the system_boot event included in main.bgs and must include the
"export" prefix in order to be used by a script that ap.bgs is imported into.
Figure 7 - ap_init_mode
The ap_init_mode procedure initializes the variables associated with Access Point mode functionality used by
the application logic contained within ap.bgs.
The ap_start_mode procedure called in main.bgs is responsible for all of the necessary processes, which
includes setting the Access Point mode configuration variables, required to start Access point mode. The
procedure must include the prefix "export" in order to be used by a script ap.bgs is imported into.
Figure 8 - ap_start_mode()
Silicon Labs
Page 8 of 18
First, the flash locations where the IPV4 address is stored is read and if the location is not empty (a value has
been stored previously), the value read is used as the IPV4 address associated with Access Point mode. If the
flash memory location is empty, a default value is used and then saved to the flash location. The flash location
allocated for the IPV4 netmask is then read and if the value has been set (a value has be stored previously) the
value is used as the IPV4 netmask associated with Access Point mode. If the value retrieved is zero, a default
value is used and then saved to the flash location. After the appropriate values are saved for the IPV4 address
and netmask, the tcpip_configure API method is called to set the final TCPIP configuration to be used for
Access Point mode.
Figure 9 - ap_start_mode() cont.
Next, the DHCP and DNS configurations are set by retrieving the values saved in the appropriate flash locations
if values have been set and if not, setting them to default values. The power saving functionality is completely
disabled in this example by calling the system_set_max_power_saving_state API method with a value of 0. The
Access Point channel and Security configurations are then retrieved from the appropriate flash memory
locations and used if values are present and if not, default values are assigned and stored in flash.
Silicon Labs
Page 9 of 18
Figure 10 - ap_start_mode() cont.
The last two operations included in the ap_start_mode procedure are retrieving setting the Access Point SSID
and pass phrase values from the appropriate flash locations if values have been set and if not, setting a default
value for SSID and disabling security if a pass phrase has not been set.
The sme_ap_mode_started event is received after Access Point mode has been successfully started. The
content within the sme_ap_mode_started event is responsible for setting the final parameters for the Access
Point configuration.
Figure 11 - sme_ap_mode_started()
The important API method to take note of is the https_add_path method. The https_add_path is used to
configure a new HTTP server paths. The possible paths include BGAPI, internal flash, and the external SD
memory card. Two new paths are added here, one to the internal flash and the other to BGAPI using the URL
constants defined at the top of ap.bgs.
Figure 12 - https paths
Silicon Labs
Page 10 of 18
3.4
sta.bgs
The sta.bgs BGScript file implements the Station Mode functionality of the http_serv example project. The
sta_init_mode procedure is called from within the system_boot event included in main.bgs and must include the
"export" prefix in order to be used by a script sta.bgs is imported into.
Figure 13 - sta_init_mode()
The sta_init_mode procedure initializes the variables associated with Station mode functionality used by the
application logic contained within sta.bgs.
The sta_start_mode procedure called in main.bgs is responsible for all of the necessary processes, which
includes setting the Station mode configuration variables,required to start Access point mode. The procedure
must include the prefix "export" in order to be used by a script ap.bgs is imported into. The first procedure called
within sta_start_mode, sta_set_read_ipv4_config, retrieves the IP configuration from the appropriate PS keys
and saves the read values into the station mode configuration variables used by sta.bgs.
Figure 14 - sta_start_mode()
Figure 15 - sta_start_mode() cont.
Silicon Labs
Page 11 of 18
3.5
main.bgs
The main.bgs BGScript source file imports the three companion BGScript source files so that the entire
BGScript application is contained within main.bgs, the script file specified to be used in the project configuration
(project.xml).
Figure 16 - Imported Files
The system_boot event performs the necessary setup operations when the WF121 is booted.
Figure 17 - system_boot()
First each of the imported BGScript files (ap.bgs, sta.bgs, and api.bgs) are initialized by calling their respective
init procedures, then operating mode is set to a default operating mode (Access Point Mode). Next, if there is an
operating mode stored in flash, it is read and the operating mode is set to the saved value instead of the default
value. After the operating mode has been set correctly, it is activated by calling the sme_set_operating_mode
API method. Last, the MAC address is retrieved using the config_get_mac API method. If an appropriate MAC
address is returned, the WiFi radio is turned on using the sme_wifi_on API method.
The sme_wifi_is_on event is triggered upon the successful activation of the Wi-Fi radio.
Figure 18 - sme_wifi_is_on()
Silicon Labs
Page 12 of 18
The script within the sme_wifi_is_on event check to see if the current operating mode is station mode, and if
true, calls the procedures start_status_notification (for Station mode "STATUS_PIN_STA") and sta_start_mode
defined in main.bgs and sta.bgs respectively. The start_status_notification procedure is defined near the top of
main.bgs and is used to indicate the current status on the WF121 using several LED's on the development kit. If
the current operation mode is not station mode, the procedure start_status_notifcation (for Access Point mode
"STATUS_PIN_AP"), then the API method sme_start_scan is called to begin a scan for available networks
which must be completed before Access Point mode can be started. When the scan completes, the
sme_scanned event is triggered, within which, the ap_start_mode procedure defined in ap.bgs is called after
verifying the current operating mode is Access Point mode.
Silicon Labs
Page 13 of 18
4 HTML Files
4.1
index.html
The index.html source file corresponds to the home page displayed by the HTTP server operating on the
WF121. The home page includes two clickable links and information displayed representing the current
configuration of the HTTP server running on the WF121. The clickable links positioned in the top navigation bar
include a link to the "Access Point" configuration page ap.html and a link to the "Station" configuration page sta.
html, also referred to as the Wi-Fi Client configuration.
Figure - index.html
The information displayed under the "Current configuration:" label is the only information **on this page**
retrieved from the BGScript application, all other content on the page is statically defined in the index.html
source file. The data used to populate the fields for the "Current configuration:" are retrieved from the BGScript
application using an HTTP GET request targeting the resource predefined in the BGScript application source
file, api.bgs. When the page loads, the "window.onload" event calls the javascript function "doGetStatus()"
defined within the <script> tag.
Figure - doGetStatus()
Silicon Labs
Page 14 of 18
The "doGetStatus()" function creates a new HTTP GET request specifying the resource defined in api.bgs, "api
/status". After the BGScript application responds to the request with the requested data, the "updateStatus"
javascript function is called taking the data received from the HTTP server (BGScript application) as its
parameter. The "updateStatus" function then accesses the desired data parameters included in the response
data to update the information displayed for "Current Configuration:".
4.2
ap.html
The ap.html source file corresponds to the Access Point configuration page accessed by selecting the "Access
Point" link on the home page (index.html). The Access Point configuration page includes two clickable links,
"Status" which links back to the home page and "Station" which links to the Station configuration page sta.html,
and several user configurable fields representing the Access Point configuration settings.
Figure - ap.html
The user configurable fields allow the user to configure the Access Point by selecting from available pre-defined
options for "Channel" and "Security", manually entering a password, IP address an IP netmask, and selecting
check boxes to define whether or not DHCP and/or DNS is used. If DHCP is selected, the user has the option to
define a DHCP range and if DNS is selected the user has the option to define a specific URL to use. When the
Access Point configuration page loads, the existing Access Point settings are retrieved in the same way they
were retrieved on the home page loaded with the exception that the resource specified in the HTTP GET
request is "/api/ap/setting" instead of "/api/status". After the Access Point settings have been configured, the
"Apply" button is used to submit the new settings. When the "Apply" button is selected, the javascript function
"doApply()" defined within the the <script> tag is called.
Figure - doApply()
The "doApply()" function first retrieves the Access Point settings configured on the page currently and stores
them in the "myCurrentSettings" variable. Then the settings contained in the "myCurrentSettings" variable are
then compared with the settings contained in the "myStoredSettings" variable which was populated when the
page initially loaded with the current settings retrieved from the BGScript application. For each setting
configured on the page that does not match stored setting, an HTTP POST request is sent to update the value
stored by the BGScript application using the "doStoreSetting" function.
Silicon Labs
Page 15 of 18
Figure - doStoreSettings()
After each of the new settings has been updated, the "doStoreMode" function is called followed by a call to the
"doReboot" function. The "doStoreMode" function initiates an HTTP POST request specifying the "/api/mode"
resource and send the value of 2 which the BGScript application uses to set the correct operating mode for the
WF121. The "doReboot" function initiates an HTTP GET request specifying the "/api/reboot" resource for which
the BGScript application initiates a reboot of the module so that the new Access Point configuration settings will
take affect.
4.3
sta.html
The sta.html source file corresponds to the Station configuration page accessed by selecting the "Station" link
included on both the home page (index.html) and the "Access Point" configuration page. The Station
configuration page includes two clickable links, "Status" which links back to the home page and "Access Point"
which links back to the Access Point configuration page ap.html, and several user configurable fields
representing the Station (Wi-Fi Client mode) settings.
Figure - sta.html
The "Available networks:" drop down menu is populated when the page initially loads. A list of available
networks is retrieved from the BGScript application with an HTTP GET request specifying the "/api/networks"
resource.
Silicon Labs
Page 16 of 18
Figure - doGetNetworks()
The user configurable settings include a drop down menu of the available networks retrieved when the page
loaded, an SSID and Password text field, and a check box allowing the user to select whether or not use DHCP.
After Station mode settings have been configured, the "Apply" button is used to submit the new settings. When
the "Apply" button is selected, the javascript function "doApply()" defined within the the <script> tag is called.
Figure - doApply()
The "doApply()" function first retrieves the Station mode settings configured on the page currently and stores
them in the "myCurrentSettings" variable. Then the settings contained in the "myCurrentSettings" variable are
then compared with the settings contained in the "myStoredSettings" variable which was populated when the
page initially loaded with the current settings retrieved from the BGScript application. For each setting
configured on the page that does not match stored setting, an HTTP POST request is sent to update the value
stored by the BGScript application using the "doStoreSetting" function.
Figure - doStoreSettings()
After each of the new settings has been updated, the "doStoreMode" function is called followed by a call to the
"doReboot" function. The "doStoreMode" function initiates an HTTP POST request specifying the "/api/mode"
resource and send the value of 1 which the BGScript application uses to set the correct operating mode for the
WF121. The "doReboot" function initiates an HTTP GET request specifying the "/api/reboot" resource for which
the BGScript application initiates a reboot of the module so that the new Station configuration settings will take
effect.
http://www.silabs.com
Silicon Laboratories Inc.
400 West Cesar Chavez
Austin, TX 78701
USA
Simplicity Studio
One-click access to MCU and
wireless tools, documentation,
software, source code libraries &
more. Available for Windows,
Mac and Linux!
IoT Portfolio
www.silabs.com/IoT
SW/HW
www.silabs.com/simplicity
Quality
www.silabs.com/quality
Support and Community
community.silabs.com
Disclaimer
Silicon Laboratories intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software implementers using
or intending to use the Silicon Laboratories products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each specific device, and
"Typical" parameters provided can and do vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Laboratories reserves the right to
make changes without further notice and limitation to product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the
included information. Silicon Laboratories shall have no liability for the consequences of use of the information supplied herein. This document does not imply or express copyright licenses
granted hereunder to design or fabricate any integrated circuits. The products are not designed or authorized to be used within any Life Support System without the specific written consent
of Silicon Laboratories. A "Life Support System" is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in significant
personal injury or death. Silicon Laboratories products are not designed or authorized for military applications. Silicon Laboratories products shall under no circumstances be used in
weapons of mass destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons.
Trademark Information
Silicon Laboratories Inc.® , Silicon Laboratories®, Silicon Labs®, SiLabs® and the Silicon Labs logo®, Bluegiga®, Bluegiga Logo®, Clockbuilder®, CMEMS®, DSPLL®, EFM®, EFM32®,
EFR, Ember®, Energy Micro, Energy Micro logo and combinations thereof, "the world’s most energy friendly microcontrollers", Ember®, EZLink®, EZRadio®, EZRadioPRO®, Gecko®,
ISOmodem®, Precision32®, ProSLIC®, Simplicity Studio®, SiPHY®, Telegesis, the Telegesis Logo®, USBXpress® and others are trademarks or registered trademarks of Silicon Laborato-
ries Inc. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. All other products or brand
names mentioned herein are trademarks of their respective holders.
