NetBurner 3.5.0
PDF Version
 
Getting Started Guide

Introduction

How to Use This Guide

The goal of the NetBurner Eclipse Getting Started Guide is to familiarize new users with the NetBurner Eclipse (NBEclipse) interface and basic operation. NBEclipse is based on the standard Eclipse release with additional features to support development with NetBurner hardware, such as the ability to locate your NetBurner device on the network, and download an application to the device’s flash memory. Topics include:

  • How to create a new project
  • Import, compile, and execute example programs
  • Debug an example program
  • Use the application wizard to create a new program
  • Various tips on useful features of the NBEclipse environment

Source Code for Example Programs

Source code for the examples in this document are located in the \nburn\examples directory of your NetBurner tools installation.

Hardware Setup

This document assumes you have a working hardware platform on which you can run the examples. Your NetBurner development kit hardware is pre-programmed with an example application at the factory. Before executing the examples in this document, it would be a good idea to connect your NetBurner device to your computer and verify you have serial and network communication with the device as described in the NNDK Quick Start Guide.

Software Installation

NetBurner software tools run on Microsoft Windows and OSX. When you receive your development kit there will be a bright red card with a keycode. Register this keycode at https://support.netburner.com to download the development tools.

Upgrading From a Previous Installation

Do not install over an existing version when upgrading from a previous version of the NetBurner tools. The upgrade requires that you either rename or uninstall the existing installation directory. The recommended procedure is as follows:

  1. Backup any existing projects you want to save, especially if they are in the NetBurner tools installation directory.
  2. Rename the existing tools installation folder. For example, if upgrading from revision 2.8.8, rename \nburn to \nburn2p8p8, then install the new version to \nburn. This way you can always get back to the previous installation and environment by renaming \nburn2p8p8 to \nburn.

Java Installation

NBEclipse requires the 64-bit Java Runtime Environment (JRE) revision 1.8 or higher. If there is no JRE installed, then you will receive an error message when starting NBEclipse stating that it cannot find the JRE executable. The JRE is free from http://java.sun.com. Download either the Java SE (Standard Edition) Development Kit (JDK) or Runtime Environment and follow the installation prompts. You may need to restart your computer after installation is complete.

Note
NBEclipse tools version prior to 3.0 require the 32-bit JRE.

Debug Port

Throughout this guide, we will refer to the "serial debug port". The serial debug port is one of the RS-232 ports that can be used to interact with your NetBurner device in the example programs. Stdout, stdin, and stderr are mapped to the debug port by default, so when you use functions like printf(), scanf(), gets(), they read and write to the serial debug port. Mapping of the stdio is configurable, as you can disable the serial debug port and use it as a general purpose UART, or reassign the stdio file descriptors to use other serial or network interfaces. Debugging in NBEclipse on network-enabled platforms will occur through the Ethernet connection, while debugging on non-network platforms will use the serial port.


Platform Overview

NetBurner Development Platform Choices

Your NetBurner Network Development Kit provides two options for development:

  1. NBEclipse Integrated Development Environment (IDE)
  2. Command line tools using the GNU make utility.

The choice of what platform you wish to use depends on personal preferences. The command line tools use makefiles, which are included for every example program and can be used as a starting point for your own makefiles. The make utility can also be invoked from within other IDEs and code editors such as Microsoft Visual Studio.



Project Management

The following points are useful to users who have not used a similar type of project manager. There are three primary methods to maintain and build a project:

  1. Use NBEclipse to manage the project with the project files located in the NBEclipse workspace. This is the recommended method.
  2. Use NBEclipse to manage the project with the project files located in an existing directory outside the NBEclipse workspace.
  3. Configure NBEclipse to use an external makefile that you maintain.

NBEclipse Key Points

  1. NBEclipse uses a "workspace" in which projects are created and source files are copied.
  2. All source code files must reside in the project's "src" folder.
  3. If using the web server, all HTML and associated files must reside in the project's "html" folder.
  4. All recognized files in a project directory will be compiled. Recognized files have extensions of .c, .cpp, and .s (.s is an assembly language file).
  5. The Project Explorer tab on the left side of the NBEclipse IDE is a navigation window like a file browser, it is not a file project manager. All recognized files will be built as part of the application. If you have non-project related files in your project directory and wish to see only the project files in the tab, you can select a filter to display only source code files.
  6. To download an application to you NetBurner device, select "Run as NetBurner Application" from the project's Build Targets folder.
  7. Application build output files such as .o, .elf, .map,.bin and .s19, and .bin will be written to project sub-directories named "Release" and "Debug" that correspond to the type of build executed. The .bin and .s19 files are the application image files.
  8. The keyboard shortcut <cntl> b will build the active project.
  9. The keyboard combination of <cntl> <space> invokes function auto-complete.



Creating Projects and Importing Files

This is the most common type of project creation. It will be used to build and run example programs, and is a good starting point for your own projects. By "empty project" we are referring to creating a project without running the Application Wizard to auto-generate a minimal application. After we create the project we will use the project import feature to import source code files from an example into the project.

  1. Create an empty project.
  2. Import source files by right-clicking on the project name and using the Import feature from the drop down menu.
  3. Build the application and download to your NetBurner device.

Create a New Project

From the main menu, select File->New->Project:




Select the NetBurner Project Type

Select the NetBurner project type, then select Next:




Specify Project Name and Executable Option

Enter your project name in the Project Name field (it is best not to use spaces with gcc tool chains). In this example we entered "SimplHtml", since that is the example we will import. Make sure the Executable is set to: "NetBurner C++ Project".

Warning
Be sure to select NetBurner Device Executable, do not select the C/C++ option.
Note
You can create a project in a directory outside of your workspace by unchecking the Use Default Location checkbox, and using the Browse button to select the directory containing the source files.






Project Configurations

The default options for the project configurations are both Release and Debug. Leave the defaults and select Next.



Select Your NetBurner Target Device

There are two ways to select your target NetBurner device:

  1. Click on the Search button to bring up a list of NetBurner devices on your network (device must be operational).
  2. Manually: Click on the Target Platform drop down box to select your platform, then type in the IP address.



    When using the Search feature, select the device in the list that corresponds to the MAC address printed on the label of your NetBurner device. In the image below we can see the device type, MODM7AE70, it's MAC address, and it's IP address. It will then fill in the platform and IP address for you. When done select Next.





Application Wizard

Since we are creating an empty project and will be importing our own source files we do not want to select any items here. However, if you wish to generate a minimal application using the Application Wizard, select both Standard Initialization and Web Server. This will generate a main.cpp source file to use as a starting point for your application.

Select Finish to complete the project creation.





New Project Created

You will now see your new project in the Project Explorer pane. At this point we have a project, but still need to import our source files (if you did not use the Application Wizard).





Import Example Source Files to the Project SRC Folder

The next step is to import the source files of an example. NBEclipse uses a make utility to manage projects, and will attempt to build all source files in your project directory. Do not import non-source code files, such as .o, .elf, .map, .mk, auto-generated htmldata.cpp files, etc. NBEclipse will store all output files similar to these in project subdirectories named "Release" and "Debug" corresponding to the build type preformed.

For this demonstration we will use "\nburn\examples\Web\SimpleHtml". The first step is to right-click on your project in the NBEclipse Project Explorer pane:





Next select the General->File System, then select Next:





Select the Browse button to bring up a file selection window, navigate to \nburn\examples\Web\SimpleHtml, and select the OK button:





Once back at the File System dialog box, click on the ">" symbol next to the SimpleHtml name to open the tree structure. You can see that there is a folder named src and a folder named html. We want the files in both folders, so select the checkbox next to the name "SimpleHtml", which will select all folders underneath it. Note: the makefile you see is only used for command line builds, but it does no harm to import it as well.




Select Finish, which will import the files and automatically build the project. You can view the status of the build process in the console window, located in the lower right corner of your screen. In the Project Explorer, click on the ">" symbol next to SimpleHtml. Some important items of note:

  • Build Targets has two functions: downloading code to your device, and rebuilding the system libraries if needed.
  • The src folder contains all your source code files, such as main.cpp.
  • The html folder contains all your web based code.
  • The overload directory is used to override any system library files. See the example in \nburn\examples\OverloadDirectory for more details.





Open your main.cpp source file

Clicking on the ">" symbol next to the src folder, you can open main.cpp in the editor





Project Import Complete

At this point you have a project complete with source code files. You can use the editor to modify both src and html files. If you wish to open a html file in text mode to do things like add dynamic content tags such as CPPCALL, VARIABLE, etc, right-click on the html file and use the Open With option to select the text editor:





By default, any time you modify and save a source file, the system will automatically build the application. If you prefer to turn off the auto-build option, to build the project: from the main menu select Project->Build Project, or use the <cntl> b keyboard shortcut.





Download the Application to Your Device

Now that an application image has been built, the next step is to download the binary image to your NetBurner device. NBEclipse can simultaneously handle multiple NetBurner hardware platforms of the same or different types. For example, multiple MODM7AE70 core modules, or a mix with some MOD54415 modules. Targeting a project to a specific hardware device, is accomplished by creating a Run Configuration for release mode project builds, or a Debug Configuration for project debug builds. An important part of such a configuration is associating the device's IP address with the project so NBEclipse knows where to download the project's binary image.

When you create a new project and select the download option for the first time, NBEclipse will create a Run Configuration for you (Run and Debug Configurations can also be created manually). First select your project by left clicking on it in the Project Window:





Then click on the Run button in the upper right corner of NBEclipse:





The Run As dialog box will appear. Select NetBurner Application, which will run the application on the remote system: When you click the OK button, NBEclipse will download the binary image to the remote device and reboot it.





The application should now running on the device. If you do not remember the IP address of the device, you can find it using the "Find" window in the lower left of NBEclipse. In the screen shot below there are 3 devices. The device running SimpleHtml has IP address 10.1.1.196.





View the Device Web Page

Opening a web browser and typing 10.1.1.196 in the URL field:





If you now look at the upper left side of NBEclipse, you will see the configuration set to Run, and the project set to SimpleHtml for the configuration.





View Serial Port Status Messages with MTTTY

All NetBurner examples make use of the debug/console serial port to provide status messages. You will need to have a serial connection to your device either through USB or the DB9 on the development board, depending on your hardware configuration. You can then use the MTTTY serial terminal application to view the serial output. To open MTTTY:





When the device boots the SimpleHtml application you will see:





Debugger

In the previous section we created and ran a project in release mode. To use a debugger, the application must be built in debug mode. All debuggers require the code be built in a different manor than a release build:

  • Code optimization is disabled
  • If the platform uses external SDRAM with the internal SRAM acceleration for stacks, buffers and variables, it is disabled
    NBEclipse uses a network debugger. This means that an application must be able to at least boot through network initialization so the NBEclipse agent can connect to the GDB stub on the target device.

Starting a Debug Session

We will pick up right where we left off for the SimpleHtml example project in the previous section. First, lets open main.cpp and add a variable. UserMain() is shown below:

void UserMain(void *pd)
{
init(); // Initialize network stack
StartHttp(); // Start web server, default port 80
iprintf("Application: %s\r\nNNDK Revision: %s\r\n", AppName, GetReleaseTag());
while (1)
{
}
}
#define TICKS_PER_SECOND
System clock ticks per second.
Definition nbrtos/include/constants.h:41
void OSTimeDly(uint32_t to_count)
Delay the task until the specified value of the system timer ticks. The number of system ticks per se...
Definition nbrtos.h:1719
const char * GetReleaseTag()
Returns the NNDK release tag information.
void StartHttp(uint16_t port, bool RunConfigMirror)
Start the HTTP web server. Further documentation in the Initialization section Initialization - Syste...
void init()
System initialization. Normally called at the beginning of all applications.
bool WaitForActiveNetwork(uint32_t ticks_to_wait=120 *TICKS_PER_SECOND, int interface=-1)
Wait for an active network connection on at least one interface.


Add two lines of code to create an integer and increment it:

int i = 0; and i++;


So UserMain() becomes:

void UserMain(void *pd)
{
init(); // Initialize network stack
StartHttp(); // Start web server, default port 80
iprintf("Application: %s\r\nNNDK Revision: %s\r\n", AppName, GetReleaseTag());
int i = 0; // <--- Declare variable
while (1)
{
i++; // <--- Increment variable
}
}


Previously for the Run Configuration and download we clicked on the green play button in the upper right corner of NBEclipse. This time we will click on the debug button, which is next to it on the left:





It will take a few seconds for the debugger to connect, and the NBEclipse Perspective will change from the NetBurner perspective to the Debug perspective:





At this point the code is running. To set a breakpoint on our new variable, double click to the left of the line of code. In this example it is just to the left of line 29:





The screen shot below shows the program stopped at line 29. The Variables window in the upper right shows the variable 'i', which has incremented 7 times so far.





The debugger operations are controlled with the tool bar at the top of the screen. If you hover the cursor over the icon the tool tip will describe what it does. Common features are:

  • Resume: Available when stopped at a breakpoint. Selecting it will resume the application and stop at the next breakpoint.
  • Terminate: Disconnects the debugger from the target device. The device will resume execution without any breakpoints.
  • Disconnect: Identical to Terminate.
  • Step Into: Single step into a function call.
  • Step Over: Single step to the next line of code in the current function.
  • Step Return: Execute until current function returns.
    Notes on debugging:
  • You can switch between the Debug perspective and NetBurner perspective using the NetBurner and Debug icons in the upper right corner of the screen.
  • You can edit and build your application from either perspective.
  • Hovering the cursor over variables, macros and functions in the source code window will display information on that item.
  • The upper left window displays the RTOS task stack.
  • It is recommended to terminate a debug session before starting a new one.
  • The three icons at the top left of the screen: build, debug and stop, are not used by either perspective.

Rebuilding Projects & Libraries

Rebuild Project Source Files

A project "clean" will rebuild all of the project's source code files. It does not affect the library system files associated with the project. From the Project Explorer pane, right-click on your project, then select Clean Project:





Rebuild Library Files

This is normally not necessary, but there are cases in which the user may want to rebuild the NetBurner system library files. For example, if the user made changes to system source files or added a system source file to a project's overload directory. In these cases, it's recommended to rebuild the NetBurner system library files followed by "cleaning" the project's source files.

To force a rebuild of the NetBurner library files associated with a project, double-click on Clean Project Library in the Build Targets tree:





Overload Directory

The overload directory, located inside a project, is used to override any system file by including local copies of system source or header files. This allows the user to isolate system files changes to a specific project. The overload directory provides an alternative to modifying the original system files, which would affect all projects.



To use this feature, the file to be overloaded should be placed in the overload directory under a directory structure that matches the file's location relative to the NNDK install directory.

To demonstrate the usage and configuration of the overload directory, we will show an example. Let's say the user wants to overload the system's timezone structure so that they can change the name of a timezone. Perhaps the user is deploying their device in a non-English speaking country and would like to change the language used for timezone names. The timezone names are defined in a system file located in the following directory:

    /nburn/nbrtos/source/timezones.cpp

Therefore, the directory structure is replicated inside the overload directory with the following structure:

   <project root>/overload/nbrtos/source/timezones.cpp

The directory structure can be created by right-clicking the overload directory and selecting New->Folder. The overload directory must have a matching directory structure to the path of the system file to be overloaded. For this example, the overload directory should look like the following:




Next, the modified source file must be placed in the correct path in the overload directory. The file can be drag and dropped in place. Alternatively, the file can be imported into the overload directory by right-clicking the overload directory and navigating to Import->General->File System and navigating to the source file. After adding timezone.cpp, our overload example would look like the following:




Next, the project properties must be configured so that the C++ compiler knows to include the path to the overloaded source file. This can be done by right-clicking the project and selecting "Properties" as shown in the image below.




Navigate to C/C++ Build->Settings, select GNU C++ Compiler->Includes.




Add the overload directory path to the "Include Paths" list by selecting the "+" logo. If utilizing C code, then the path to the overload directory should be added to GNU C Compiler->Includes as well.




After adding the overload directory path to the list of "Include Paths," the list should look like the following:




Select "Apply and Close" to apply the modifications.

Last, we need to rebuild the NetBurner system files then clean the project files (the order of operations matters). For instructions on doing so, see Rebuilding Projects & Libraries. From this point on, modifying the overloaded source file, timezone.cpp, will automatically re-build the necessary files in the NetBurner system files when the project builds.