Introduction

The NetBurner configuration system is used to configure and store system and application defined values and data in flash memory. These values can be accessed and modified through:

The System Configuration Web Server (port 20034)
Your application
Your web page interface
Serially through the Serial Config Server

The web interface also provides a convenient way of uploading a new application onto the module. While the web interface provided is fully functional, it is possible override this with a custom web interface in your application for purposes such as branding or adding/removing features.

The configuration data itself is stored and presented as JSON blobs. It's possible to access, modify, and send the entire JSON blob, or any subsection of the data, down to individual components.

Configuration Parameters

The configuration server holds the module's boot settings, network interface settings, and any custom application information you wish to save, display or modify. Your application can view and/or modify these parameters a variety of ways:

The system configuration server web page
Your own custom configuration server web page
Any type of web interface in your application
In your application code directly

The configuration system has a tree structure with "leafs". There are a number of built-in leafs described below, such as "Config", "AppData", and "Boot".

Config

Config is the top level object that contains everything else. Underneath are the AppData and Sys settings. There is also a Version field that is updated automatically when new settings are saved. The Reboot option, when checked, will force the module to reboot when the configuration record is updated.

Config.AppData

The AppData leaf is set aside at the top leaf for user application data. The application can select from the many configuration objects to store strings, integers, list boxes, etc. More information on how to use these can be found in the BasicConfigVariable NetBurner Basic Config Demo.

Config.Sys

The Sys leaf contains the device system settings such as boot parameters, application name, and network interface settings.

Config.Sys.Boot

Boot settings include:

Abort: This specifies the keys that needs to be pressed in order to break out of the normal boot sequence. This prevents anything after the init() function from running in UserMain(). This will load the serial configuration server, enable the config web interface and effectively stops the user's application from running. The default value for this is "A".
BootBaud: The baud rate that the BootUart will use.
BootDelay: How long the application will delay to wait for the Abort characters before continuing.
BootQuiet: Whether or not to display the boot output data on the BootUart.
BootUart: The UART used by the system to display output related to the device booting.
Password: When this is set along with User, both will be required when making changes to the congif settings, or when updating the user application.
Serial Config: There are four different options for this, which are outlined below.
- DuringBoot: This will make the serial configuration server available during the boot process by using the Abort characters set above.
- AlwaysEnabled: This will set the serial configuration server to always be available through the BootUart. Note that if this is selected, attempting to receive other serial input through the BootUart (such as debug commands, etc.) has the potential to break the configuration record.
- PauseAfterBoot: This option will cause the boot process to pause indefinitely before the user's application is launched (specifically after init() is called), and will cause the serial configuration server to be enabled over the BootUart. The user's application can be resumed by typing boot.
- Disabled: This prevents the serial config server from being enabled, and does not pause during the boot process, which stops the user from being able to enter the Abort character sequence.
User: When this is set along with Password, it must be entered when trying to make changes to the configuration record's values or uploading a new application to the module.

Config.Sys.NetIf

The settings underneath NetIf deal with the different network interfaces available on the module. This will include all of the Ethernet ports, as well as any Wifi ports available. What is actually listed underneath these interfaces will depend on the interface itself. Common settings are listed below:

Config.Sys.NetIf.Ethernet0

Ethernet settings include:

DeviceName: A name given to the interface, which is used to register for DDNS and NetBIOS.
DhcpDiscoverSec: How long to wait after boot before sending a DHCP Discover message.
DiscoveryReportInterval: How often a device should report itself to the discovery server.
DiscoveryReportUrl: The location of the discovery server. By default, this points to NetBurner's discovery server. However, if desired, this field can changed to be blank so that the device does not report itself. It can also be set to another URL if the user wishes to run their own discovery server.
MAC: The MAC address of the interface.

Config.Sys.NetIf.Ethernet0.IPv4

IPv4 Settings include:

ActiveAddr: The current IPv4 IP address in use.
ActiveDNS1: The current IPv4 DNS server (1) in use.
ActiveDNS2: The current IPv4 DNS server (2) in use.
ActiveGate: The current IPv4 gateway in use.
ActiveMask: The current IPv4 mask in use.
AutoIPAddr: The current IPv4 auto address in use.
AutoIPEn:
Mode: Specifies which method to use to acquire IPv4 active values. The options are as follows:
- DHCP: Use the values provided by the DHCP server.
- DHCP w Fallback: Try to get values from the DHCP server, and use the static values as a backup.
- Static: Use the static values defined in the interface's config record.
- Disabled: Disable the interface.
StaticAddr: The manually configured IPv4 IP address.
StaticDNS1: The manually configured IPv4 DNS(1).
StaticDNS2: The manually configured IPv4 DNS(2).
StaticGate: The manually configured IPv4 gateway.
StaticMask: The manually configured IPv4 mask.

Config.Sys.NetIf.Ethernet0.IPv6

IPv6 settings include:

ActiveAddr: Lists the current IPv6 addresses in use.
ActiveDNS: Lists the current IPv6 DNS servers in use.
ActiveRoutes: Lists the current IPv6 routes in use.
Mode: Specifies which method to use to acquire IPv4 active values. The options are as follows:
- DHCP: Use the values provided by the DHCP server.
- DHCP w Fallback: Try to get values from the DHCP server, and use the static values as a backup.
- Static: Use the static values defined in the interface's config record.
- Disabled: Disable the interface.
StaticAddr: The manually configured IPv6 IP address.
StaticDNS1: The manually configured IPv6 DNS(1).
StaticDNS2: The manually configured IPv6 DNS(2).

The Configuration Web Interface

The device's configuration web server is available on port number 20034. To view in a web browser, type the device's IP address followed by the port number. For example, "10.1.1.100:20034". The default system configuration server web page is shown below. Note that you can easily create your own custom web page for things as simple as branding with your own logo, to formatting and adding fields in any way you wish. Clicking on the tree structure leafs will navigate through the settings.

Located on the right side of the interface, you will also notice that there are several buttons. These provide the following functionality:

Expand All: This expands the entire config tree structure.
Collapse All: This collapses the entire config tree structure.
Update Record: This updates the config record with the values that are currently entered in config structure on the web page.
Download Config: Download the configuration object in JSON.
Restore Config: Upload a JSON configuration object.
Raw Config Page: Display a non-stylized version of the web interface, which can be edited.
NB Discover: This takes you to NetBurner's Discover page.
Discover Local: Discover device on the local network, Internet access in not required.

The Update Application section provides for an application update by selecting a .bin file. Use the Choose File button to select the image, followed by selecting Send File.

Serial Configuration Interface

In addition to the web interface, it's possible to navigate and modify the config record through a serial terminal. To do this, you will need to enter the serial config server through the BootUart using a method defined by the SerialConfig option in the Boot settings outlined above.

The most common method will be to type in the string specified by the Abort setting listed in the Boot configuration section. Reset the module and send the abort string before the boot timeout expires. The boot delay text is:

Type \<Abort Value>\ to Abort boot...

The default Abort Value is a capital 'A'. Upon successfully entering the serial configuration monitor, the > prompt will be displayed:

Navigating through the config data via the serial menu has been designed to operate much like a standard file system. Typing the name of a config object will move you into that section of the config data, much like navigating into a directory through a command prompt. Where you are in the config structure will be displayed at the prompt. For example, from the initial prompt, >, if you were to type Config.Sys and hit enter, the prompt would then read Config.Sys.>, illustrating that you are currently at the system settings for the config object.

In addition, several commands have been added to aid in navigating and modifying the config data, as well updating the device. Typing "help" at the prompt will display a list of these commands. Each of these is explained below:

help: Displays the commands that can be used in the serial config system.
boot: This will exit the serial config server, and continue to boot the user's application.
reboot: This will reboot the module.
flash: This will allow to you upload a new application serially. To do this in MTTTY, after typing this command hit "F5" to open a file dialog box and select a new .bin file to upload.
<configvar>?: Type the name of a config variable followed by a "?" to list the config structure underneath the config variable specified. For example, typing Config? will show the entire contents of the config structure, while Config.Sys will show all of the system settings.
<configvar>=<value>: This will assign a value to a specific config variable.
..: This will take you up one level in the config object structure from the current position.
ls: This will show the current level of the config object.
save: This will save any changes made to the values stored in the config object.

Creating a Custom Web Interface

The config web interface was designed so that it could be easily replaced by customers with their own web interfaces and logos. To do this, simply replace <NNDK Install Directory>\nbrtos\source\ROOT.html with your own file, and rebuild the system libraries as outlined in the Rebuilding Projects & Libraries NBEclipse Guide.

If you simply want to replace the logo show in the config web interface, replace LOGO.gif with your own image, and rebuild the system libraries as mentioned above.

An example has been setup that shows how the current config web interface has been structured and built. It can be found in the examples folder of your NNDK install at <NNDK Install Directory>\examples\Configuration\BasicWebConfig.

Configuration API Examples

There are several examples that outline how to properly use NetBurner's config objects. These can all be found in the examples folder of your NNDK install at <NNDK Install Directory>\examples\Configuration\. They are listed here with brief descriptions for your convenience.

BasicConfigVariable Basic Config Variable: This program shows the basics of using NetBurner's config system objects.
BasicWebConfig Basic Web Config: This program shows the basics of using NetBurner's config system and presenting the information through a dynamically generated web interface.
CustomWebConfig Custom Web Config: This program shows how to use NetBurner's config system combined with a more complicated web interface featuring BootStrap and jQuery.