NetBurner 3.5.6
PDF Version
Device Discovery and Configuration

Introduction

Device discovery and configuration can be accomplished in a number of ways, including methods that are platform independent, including Windows, macOS, Linux, tablets and mobile phones.

Note
Please refer to the Production & Deployment section of this document for methods and utilities designed to program and configure devices in a production environment.

Device Discovery Methods:

  • If the device and computer have Internet access, open a web browser and go to 'discover.netburner.com'.
  • Use the localdiscover utility located in \nburn\pcbin\localdiscover. This is a multi-platform utility written in Golang for Windows, macOS and Linux. The compiled version can be distributed to your customers, but not the Golang source code.
  • Use the Python find utility, located in \nburn\pctools\find.
  • Use the debug/console serial port.

Device Configuration methods:

  • Interactively using a web browser to access the device's Configuration Server
  • Sending a JSON object and a utility such as wget (See Production & Deployment)
  • The device's serial interface to the Configuration Server

The primary configuration method is through the device's Configuration Web Server. By utilizing a web server, a device can be configured from any platform or operating system. The underlying configuration mechanism is handled through a JavaScript Object Notation (JSON) object. This will be described in more detail later, but the important point is that it provides a simple interface that can be used by non-embedded developers (e.g. web developers) to interact and configure the device. The implementation is also designed to enable you to add any application specific information to be stored and accessed in the same manor, such as calibration values, set points, etc.

You are also able to create your own configuration web interface that will appear in place of the default interface. In this way you can organize and present data in the appropriate way for your customers, as well as add your own custom logo, images and descriptions. Examples are provided.

Configuration Procedure

  • Connect your NetBurner device to a network with Internet access.
  • Open a web browser on your host computer and go to discover.netburner.com. You will see a list of devices on your network. (If the device does not have Internet access, use the localdiscover utility instead).

All system and application settings can now be viewed and/or modified by navigating the tree structure.


Using discover.netburner.com:




Using localdiscover utility:




The "Device" link will take you to the device application web page. The "ConfigPage" link will take you to the device configuration web page, as shown below:




Configuration Settings

Config

Top level configuation leaf containing System (Sys) and Application Data (AppData) configuration leafs. AppData will only be populated if an application uses the configuration system for storage/configuration of application specific items, as opposed to common system configuration settings.

Setting Description
Version Configuration system write counter. Increments each time new values are saved.
Reboot Check this option to reboot the system once new values are saved

Update Application

A new application can be programmed into the device by choosing an image file and selecting the "Send File" button. Note that the Reboot checkbox should normally be checked so that the device reboots and runs the new application that was sent.

Config > Sys

System settings

Setting Description
Application Name of running application.
Platform Name of hardware platform, such as MOD54415


Config > Sys > BOOT

Boot settings.

Setting Description
Abort Character or string to send to the boot serial port to abort the application boot process and enter the Serial Port Configuration interface. Default is 'A'.
BootBaud Boot serial port baud rate. Default is 115200, N, 8, 1.
BootDelay Number of seconds to delay starting the application. This is the time available to send the Abort character or string. Default is 2 seconds. DO NOT SET TO 0.
BootQuiet At power-up the boot serial port will send the message: "Waiting 2 seconds to boot..." Enabling quiet boot will disable this message. Default is off.
BootUart Designated boot UART number. Varies by platform, but typically default is 0.
User Optional user name for password protection of the web page interface.
Password Optional password to access the web page configuration interface.
SerialConfig Boot options for the Serial Port Configuration interface:
- During Boot (default)
- Always Enabled
- Pause after boot
- Disabled
Note
The password can be reset through the Serial Port Configuration interface.


Config > Sys > NetIf

The NetIf section contains settings for all available network interfaces. For example, if the system has a single Ethernet interface, there will be a section named Ethernet0. If there are two Ethernet interfaces, the second will be Ethernet1. If a Wifi interface is available it will be listed as well.

Config > Sys > NetIf > Ethernet0

Settings for each Ethernet interface

Setting Description
DeviceName Interface name used for DNS and NetBIOS
DhcpDiscoverSec Number of seconds after boot to wait before sending a DHCP Discover message. Default is 1.
DiscoveryObfuscate Send data to Discover Server obfuscated rather than plain text for security. Default is enabled.
DiscoveryReportInterval How often to report to Discovery Server in seconds. Default is 900.
DiscoveryReportUrl Name of Discover Server. Default is: discover.netburner.com/DevicePost.
MAC MAC address
SupressDefault Disable Ping and UDP Echo ports. Default is not supressed.
VlanTag Virtual Network tag number. Default is 0


Config > Sys > NetIf > Ethernet0 > IPv4

IPv4 network interface settings.

Setting Description
ActiveAddr Current IP address.
ActiveDNS1 Current DNS1 address.
ActiveDNS2 Current DNS2 address.
ActiveGate Current Gateway address.
ActiveMask Current IP Mask.
AutoIPAddr Auto IP address.
AutoIPEn Enable AutoIP feature. Default is enabled.
EnableMacmDNS Enable device access by name in the format: nburnxxxxxx.local, where xxxxxx is the last 6 digits of the MAC address. Default is disabled.
LocalName Specify device access by name in the .local format. For example: mydevice.local.
Mode IP Address Mode:
- DHCP (default)
- DHCP with fallback to static
- Static
- Disabled
StaticAddr Static IP address.
StaticDNS1 Static DNS1 address.
StaticDNS2 Static DNS2 address.
StaticGate Static Gateway address.
StaticMask Static IP Mask.


DHCP With Fallback Details

After boot, the first DHCP Discover message will be sent once the network link is active. Note that if the network link is not active, such as when a network cable is not connected, DHCP will not start, and the fallback to a static address will not occur.

Once DHCP starts it will attempt to get the IP settings from a DHCP server. If not successful, it will retry 4 more times at 8, 16, 23, and 64 seconds. If not successful, then the fallback to static IP address settings will occur.

For custom applications, the retries can be modified in the DHCP Client header file (may be moved to constants.h in a future release). The defaults are shown below:

#define DEFAULTTIMEOUT (4)
#define DEFAULTRETRY (5)


Config > Sys > NetIf > Ethernet0 > IPv6

IPv6 network interface settings main leaf. Note: refer to DHCP With Fallback Details section above.

Setting Description
Mode IP Address Mode:
- DHCP (default)
- DHCP with fallback to static
- Static
- Disabled
StaticAddr Static IP address.
StaticDNS1 Static DNS1 address.
StaticDNS2 Static DNS2 address.


Config > Sys > NetIf > Ethernet0 > IPv6 > ActiveAddr

Displays a list of active addresses. The number will depend on the network architecture. All devies should have at least a link local address with prefix fe80::. Other addresses can be assigned from a DHCPv6 server and routers on the network. The example below shows link local, DHCPv6 and a router.

0 fe80::203:f4ff:fe07:386b
1 2600:1700:410:190f:203:f4ff:fe07:386b
2 2600:1700:410:190f::2000


Config > Sys > NetIf > Ethernet0 > IPv6 > ActiveDNS

Displays a list of active DNS serversaddresses. The number will depend on the network architecture. All devies should have at least a link local address with prefix fe80::. Other addresses can be assigned from a DHCPv6 server and routers on the network. The example below shows link local, DHCPv6 and a router.

0 fe80::203:f4ff:fe07:386b
1 2600:1700:410:190f:203:f4ff:fe07:386b
2 2600:1700:410:190f::2000

Config > Sys > NetIf > Ethernet0 > IPv6 > ActiveDNS

Displays a list of active DNS servers.

Config > Sys > NetIf > Ethernet0 > IPv6 > Route

Displays a list of active router addresses.



The JSON Object

It is not necessary to understand the underlying JSON implementation, but for those that are interested a sample JSON object is shown below. It identifies each configuration field, which can range from a string, boolean, or a selection of values. For developers, the programmers guide and examples provide the operational details.

Warning
If you do decided to use any of the JSON configuration methods, you must first download a JSON object from your specific device. Under no circumstances should you use the example below as you actual device will likely be different in some respects.

The root of the object is Config. The next levels are AppData and Sys. AppData is available for your application to store information. Sys is used for the system configuration such as IP settings.

{
"Config":{
"AppData":{},
"Sys":{
"Application":"Simple HTML Example",
"Boot":{
"Abort":"A",
"BootBaud":115200,
"BootDelay":2,
"BootQuiet":false,
"BootUart":0,
"Password":"",
"SerialConfig":{
"Choices":"DuringBoot, AlwaysEnabled, PauseAfterBoot, Disabled", "Value":"DuringBoot"
},
"User":""
},
"NetIf":{
"Ethernet0":{
"DeviceName":"",
"DhcpDiscoverSec":1,
"DiscoveryObfuscate":true,
"DiscoveryReportInterval":900,
"DiscoveryReportUrl":"discover.netburner.com/DevicePost",
"IPv4":{
"ActiveAddr":"10.1.1.73",
"ActiveDNS1":"10.1.1.1",
"ActiveDNS2":"0.0.0.0",
"ActiveGate":"10.1.1.1",
"ActiveMask":"255.255.252.0",
"AutoIPAddr":"169.254.131.245",
"AutoIPEn":true,
"Mode":{
"Choices":"DHCP,DHCP w Fallback,Static,Disabled", "Value":"DHCP"
},
"StaticAddr":"0.0.0.0",
"StaticDNS1":"0.0.0.0",
"StaticDNS2":"0.0.0.0",
"StaticGate":"0.0.0.0",
"StaticMask":"0.0.0.0"
},
"IPv6":{
"ActiveAddr":["2602:306:b8e9:c83f::14c0","2602:306:b8e9:c83f:203:f4ff:fe0b:83f5","fe80::203:f4ff:fe0b:83f5"],
"ActiveDNS":["2602:306:b8e9:c83f:208:a2ff:fe0c:b081","2602:306:b8e9:c83f:208:a2ff:fe0c:b081"],
"ActiveRoute":["fe80::1:1"],
"Mode":{
"Choices":"DHCP,DHCP w Fallback,Static,Disabled", "Value":"DHCP"
},
"StaticAddr":"::",
"StaticDNS1":"::",
"StaticDNS2":"::"
},
"MAC":"00:03:F4:0B:83:F5"
}
},
"Platform":"MODM7AE70"
},
"Version":8,
"Reboot":false
}
}



Developer Notes

If you were writing a web interface and need only the data under Ethernet in the tree, it can be accessed by: http://10.1.1.71:20034/UI.html?CONFIG/SYS/NETIF/Ethernet

To obtain just the IP address: http://10.1.1.71:20034/UI.html?CONFIG/SYS/NETIF/Ethernet/IPv4/ActiveAddr


Recommended Examples: The following examples are recommended to begin evaluating the platform. They are located in the \nburn\examples directory.

  • ShowInterfaces
  • \Configuration\Web\BasicWebConfig



Configuration Security

One of the features of NetBurner 3.0 is that each device is configured though its own configuration web interface. Data sent and received through the network interface has three options for security:

  • Open: No security, plain text
  • Obfuscated: Encrypted, but without TLS and a secure certificate and private key
  • Secure: Encrypted with TLS and a certificate and private key



Serial Configuration Server

Network connectivity is not required to use your NetBurner device. If enabled, the Configuration Server can be accessed through the device's serial port. The configuration tree is exactly the same as what you see on the web interface and in the JSON object. For example, the Ethernet0 settings are located at Config > Sys > NetIf > Ethernet0.

The serial port interface is located on UART0 by default. It can be modified and enabled/disabled in the Config > Sys > Boot level of the Configuration Server.



Serial Configuration

To access the serial port configuration:

  • Connect a cable to the serial port selected as the BootUart
  • Run a serial terminal program such as MTTTY
  • Reset the device, and type a 'A' when prompted to Abort the boot sequence


You are now in the serial configuration mode as indicated by the '>' character. Typing "help" will display the help menu.


Typing the "ls" command displays the next level of the tree, which is Config since we are at the root level. In this example we will set the Static IP values. Note that to change from DHCP to static, we must also change the Mode option from DHCP to Static. To navigate to the next level you type in the name of that level. For example, to go to the Config level:


The prompt will show the current location, in this case Config>. In the same manor to navigate to the IPv4 settings the level names are typed into the terminal. Note that tabbed auto-completion is also available.


At any level, typing a "?" will display the current values of that level and all levels beneath in the JSON object format. For example:


In this example we are interested in the static IP settings. There are two choices to set them: from the IPv4 level by including the name of the next level and the value, or by going down to each level individually and entering just the value. In this case we will stay at the IPv4 level and include the name of the static item we want to set. To set the StaticAddr type: StaticAddr="10.1.1.99". We will also type a "?" to see the changed value:


In the same manor we will set the Mask, Gateway and DNS. To set the Mode we will need to either include the Mode level in the setting string or go to the Mode level, since the setting is a Choices selection and not a simple string like the static IP settings. To accomplish this from the IPv4 level type: Mode.Choices="Static". If you navigate the to Mode level, the command would be: Choices="Static". At this point the unsaved settings are:


Warning
From the settings display you can see that the Mode selector control has two settings: Choices and Value. The Choices are values that appear in the web page selector control and you do not want to modify them. Only modify the Value to one of the Choices values.

To store the modified values in the Configuration Record in Flash memory, type #save. This will store the values, but the IP settings will not take effect until the device is rebooted.

Serial App Downloads

Just as with the select file and upload feature of the web interface, applications can be uploaded to your device using the Serial Configuration Server.

The procedure is:

  • Abort the boot process type typing 'A' when prompted to enter the Serial Configuration server mode. Note: the SerialConfig Server options includes an "AlwaysEnabled" setting so that the Serial Configuration Server is always active and a reboot and Abort is not required. This can be especially useful during development if you are not connecting your device to a network.
  • At the '>' prompt, type "flash"
  • When the download prompt appears, send the .bin file using your serial terminal program

The serial terminal output is shown below:

Start of Serial Configuration Server.

MAC Address = 00:03:f4:0e:21:ee
Type "A" to abort boot
Aborted to Serial Config (BOOT) to continue boot
type help for commands
>


Optional, type "help" to see a list of commands.

MAC Address = 00:03:f4:0e:21:ee
Type "A" to abort boot
Aborted to Serial Config (BOOT) to continue boot
type help for commands
>help# or <ESC> to execute command at levels other than root.
<tab> works for possible choices. <tab> ignores previously entered text
Commands are:
help (show this)
boot (boot to app)
reboot (reboot system)
flash (program app flash image)
.. (up one level in tree)
/ (up to root of tree)
ls ( List next level of tree)
save (save unsaved config changes)
Config (enter Config mode)
<configvar>? (read var)
<configvar>=value (set var)
Ex Config Seqs:
> Config.Sys.Boot?
> Config
> Config.Sys.NetIf.Ethernet0.IPv4.StaticAddr="10.1.0.100"
>
int read(int fd, char *buf, int nbytes)
Read data from a file descriptor (fd).


Type "flash" command

MAC Address = 00:03:f4:0e:21:ee
Type "A" to abort boot
Aborted to Serial Config (BOOT) to continue boot
type help for commands
>help# or <ESC> to execute command at levels other than root.
<tab> works for possible choices. <tab> ignores previously entered text
Commands are:
help (show this)
boot (boot to app)
reboot (reboot system)
flash (program app flash image)
.. (up one level in tree)
/ (up to root of tree)
ls ( List next level of tree)
save (save unsaved config changes)
Config (enter Config mode)
<configvar>? (read var)
<configvar>=value (set var)
Ex Config Seqs:
> Config.Sys.Boot?
> Config
> Config.Sys.NetIf.Ethernet0.IPv4.StaticAddr="10.1.0.100"
> flash
Begin Download


Send Application File

The device is now waiting to recive the application image file. Use your serial terminal option to send a binary file, and select the .bin file of the application you wish to send. After the file is uploaded, the device will reboot. In the display below the flash command is entered, the file is sent, and the status messages confirming the programming was complete. The device reboot informatoin of the new application begins with "Primary network interface....".

> flash
Unknown command (help for help)
Begin Download
Programming complete
Primary network interface configured for DHCP
MAC Address = 00:03:f4:0e:21:ee
Type "A" to abort boot
DHCP Namespace.
Definition dhcpd.h:39


Serial Config Settings

As mentioned previously, the Serial Configuration Server behavior has four options:

  • During Boot. Must abort boot sequence by sending an 'A'.
  • Always Enabled. Serial Configuration Server will always be active and process commands.
  • Pause After Boot. The device will boot into the Serial Configuration Server instead of the application.
  • Disabled.

The SerialConfig field is used to select the desired option. It can be done through the web page, or through the Serial Configuation Server itself. It is located in the Config > Sys > BOOT section of the tree.




From a serial termianl using the Serial Configuration Server itself. The example below uses the full path from the root, but you can also traverse the tree by entering each in succession: Config, Sys, Boot, SerialConfig. A '?' returns the JSON object's current setting and options.

Command Examples:

  • Config.Sys.Boot.SerialConfig?
  • Config.Sys.Boot.SerialConfig.Value="Default"
  • Config.Sys.Boot.SerialConfig.Value="AlwaysEnabled"
>
> Config.Sys.Boot.SerialConfig?
"SerialConfig":{
"Choices":"DuringBoot,AlwaysEnabled,PauseAfterBoot,Disabled",
"Value":"DuringBoot"
}
rimary network interface configured for DHCP
MAC Address = 00:03:f4:0e:21:ee
Type "A" to abort boot
Aborted to Serial Config (BOOT) to continue boot
type help for commands
>Config.Sys.Boot.SerialConfig.VAlueConfig leaf not found, help for help
>
> Config.Sys.Boot.SerialConfig?{
"SerialConfig":{
"Choices":"DuringBoot,AlwaysEnabled,PauseAfterBoot,Disabled",
"Value":"DuringBoot"
}
}
> Config.Sys.Boot.SerialConfig.Value="AlwaysEnabled" Value Set #save to save here and now.
Config.Sys.Boot.SerialConfig.Value. (unsaved)>
Config.Sys.Boot.SerialConfig.Value. (unsaved)> ?"AlwaysEnabled"
Config.Sys.Boot.SerialConfig.Value. (unsaved)> ..Config.Sys.Boot.SerialConfig. (unsaved)>
Config.Sys.Boot.SerialConfig. (unsaved)> ?{
"SerialConfig":{
"Choices":"DuringBoot,AlwaysEnabled,PauseAfterBoot,Disabled",
"Value":"AlwaysEnabled"
}
}
Config.Sys.Boot.SerialConfig.Value. (unsaved)>
Config.Sys.Boot.SerialConfig.Value. (unsaved)> #save
Config.Sys.Boot.SerialConfig.Value.>