Building Applications with NetBurner Command Line Tools

Command Prompt

In addition to the NBEclipse IDE, the NetBurner development kits provide command line tools that can be used to build and load applications directly onto NetBurner modules. While some prefer the simplicity associated with working from the command prompt, the command line tools can also be used to integrate with a different IDE, or to automate the build process for whichever build system you prefer. NetBurner’s command line tools are supported for Windows, macOS and Linux.

In this article, we will start with a quick example of building a NetBurner example, and then move on to the details of creating your own makefiles.

The Secret's Out. Try Our ARM® Embedded Dev Kit Today.

Netburner ARM Cortex M7 embedded Development Kit for IoT product development and industrial automation.

Or, learn more about NetBurner IoT.

Building a NetBurner Application from the Command Line

Command line builds use the make utility, and all NetBurner examples have an associated makefile.  The following demonstrates how to do a command line build of the example \nburn\examples\ShowInterfaces for a MODM7AE70 on Windows 10. The first step is to open a command prompt and navigate to the example directory. Once there, the key commands are:

CommandDescription
make -jThe “-j” option builds the application using all available processor cores, which will greatly speed up the build. Note: if you have errors, they may be easier to view by using just “make” so the display is from a single thread.
make -j loadBuilds the application and downloads the application image to a NetBurner device. If the DEVIP environment variable is defined it will be used, otherwise it needs to be added to command. For example, “make -j load DEVIP=192.168.1.1”. To set the variable in Windows: “SET DEVIP=192.168.1.140”.
make cleanDeletes all object and image files.
make -j debugBuild in debug mode.

There are also various environment variables that can be used:

VariableDescription
PLATFORMSpecifies the NetBurner platform for the build. Typically used when you have multiple NetBurner platforms, such as MODM7AE70, MOD5441X, NANO54415, and SB800EX.
DEVIPSpecifies the target IP address of your NetBurner device. If defined, you can run make -j load.

In Windows, you can set the environment variables from the control panel or you can specify them from the command prompt with the SET command. For example, typing SET DEVIP=192.168.1.140 will set the DEVIP variable to 192.168.0.140. Calling just SET DEVIP will show you what value is currently assigned. For macOS and Linux, use the EXPORT command.

It’s important to note that if you set environment variables directly from the command line in Windows, they will only be set for that particular instance of the command terminal. If you were to open a second command prompt and look at the variables value, you will see that they are still set to their default values. Additionally, if you change them from the control panel, those changes will note be reflected in any currently open command prompts. You will need to reopen them for those changes to take affect.

To build the example, type make -j from the example directory:

Use “make -j” to Build an Example

The first time you build a project it will build the system libraries, and you will see the files rapidly scrolling by. From that point forward only files that have changed will be built. When the build is complete you will see a build summary showing the build options and memory usage:

A Successful Build

The following shows an example when the load command is used. The load command invokes the nbupdate utility. If you are experiencing any difficulty in the application download, you can run the nbupdate utility from the command line to troubleshoot any issues.

Creating a Makefile for your Project

The screen shot below shows the file structure of the ShowInterfaces example we built in the \nburn\examples folder. The ShowInterfaces project folder contains:

  • The project makefile
  • The html folder for HTML source code
  • The src folder for the application source code
  • The obj folder for compiled object files
  • The release folder for the compiled application image (ShowInterfaces.bin) and compiled library files
The ShowInterfaces Example Folder Structure

In an effort to simplify makefiles, the makefile for a project focuses on identifying the source files, and then invokes another makefile, \nburn\make\boilderplate.mk, that handles the low level details common to all NetBurner projects. Here is the makefile for the ShowInterfaces example we built earlier:

NAME    = ShowInterfaces

CPP_SRC     += \
            src/main.cpp \
            src/ip_util.cpp

CREATEDTARGS += src/htmldata.cpp
CPP_SRC += src/htmldata.cpp
src/htmldata.cpp : $(wildcard html/*.*)
	comphtml html -osrc/htmldata.cpp

include $(NNDK_ROOT)/make/boilerplate.mk

Examining the Makefile

So what does all of this actually do? Let’s take a look.

The NAME field specifies the name of the .bin file that will be generated.

The CPP_SRC specifies the project’s C++ source code files. The ‘\’ continuation character is there to make it easier to read and list the source files one per line. Note that the path is relative to the project root folder, so files have a “/src” prefix. To add C files, add a C_SRC field, to add assembly language files add a AS_SRC field.

The CREATEDTARGS, CPP_SRC, and comphtml utility process the auto-generated htmldata.cpp. This file contains everything in the project’s html folder. If your application does not have a web interface, none of these lines are necessary and you can comment them out with the ‘#’ character (just in case you decide to add one later).

Finally, the boilerplate.mk file is called to complete the system processing.

To create a makefile for your project you can start with this example and change the NAME and CPP_SRC C++ file names accordingly. That is it!

Advanced Compiler Flags

There are a few makefile fields worth noting for advanced control of the GCC compiler. It is beyond the scope of this article to go into all the available compiler flags, but we will use optimization as an example. To turn off optimization for your project you would add: EXTRACPPFLAGS := -O0. Note that is a capital letter ‘O’ followed by the number zero.

FieldDescription
EXTRACPPFLAGSAffects all C and C++ files
EXTRACFLAGSAffect all C files
EXTRACXXFLAGSAffects all C++ files
EXTRAASFLAGSAffects all assembly files
EXTRALINKFLAGSAffects the linker

The Overload Feature

As of NNDK 3.x, all of our system libraries are now build individually for each project. This is a fantastic feature if you need to modify some of the predefined values or source code on a per project basis. To do this, simply create an overload directory in your root project directory. When you know the files that need to be overloaded, copy them into the overload directory, being careful to ensure that the file path from the overload directory has the same path as the original system file.

For example, if you wanted to overload nbrtos/include/predef.h then you would copy that files to project/overload/nbrtos/include/predef.h. For more information on how this works, please see our documentation.

Additional Command Line Tools

In addition to those mentioned above, there are some very useful command line tools that can be run directly from the command line. We’ve listed a few here, as well as a short description on what each does.

localdiscover

To locate your NetBurner device, localdiscover will send out a request to all of the NetBurner devices on your network and display the results in a web browser. The image below shows the device’s mac address as well as the IPv4, IPv6 and AutoIP addresses. From here, you can access the device’s configuration page, or the web page being served by the application running on the device itself.

The localdiscover App Shows Your NetBurner Device

nbupdate

nbupdate is a multi-platform command line utility. The format is: nbupdate <filename> <ip address>. For example, nbupdate ShowInterfaces.bin 192.168.1.140. If the environment variable DEVIP is set, the IP address parameter is not required. As mentioned earlier, this is the same utility invoked by running make -j load.

wget

WGET is an industry standard utility that allows you to download files over TCP/IP protocols FTP, HTTP and HTTPS. If you are using macOS or Linux, WGET is usually already installed (or can using your package manager). Windows users will need to install it, please refer to this page.

The WGET utility can be used for several things:

  • Updating the device application image
  • Retrieving device configuration information in JSON
  • Updating device configuration information in JSON

In the examples below we use a device IP address of 10.1.1.60 and an application name of myApplication.bin.

Program an Application

To program a new application into the device:

wget --post-file=myApplication.bin 10.1.1.60:20034/appupdate.html

All updates are processed by the Configuration Server running on the NetBurner device. The –post-file specifies that a POST operation is to be performed. The IP address and configuration port number are next, along with the server post destination that will always be appupdate.html.

If using authentication with a username of “user”, and password of “pass”:

wget --auth-no-challenge --user=user --password=pass --post-file=myApplication.bin 10.1.1.60:20034/appupdate.html

Read The Configuration

Read the current configuration into a file named config.txt:

wget 10.1.1.60:20034/Config

In this case the destination is Config, rather than appupdate.html. If you would like to specify a directory to store the file, use the -P option:

wget 10.1.1.60:20034/Config -P \myDir

Program New Configuration Settings

The easiest way to do this is to first read the configuration and save to a file so you have a template to work with, then edit the settings you need. Then post the configuration file to each new device:

wget --post-file=newconfig 10.1.1.60:20034/Config

Wrapping Up

It’s clear that there are a multitude of ways to build and deploy applications to your devices. We want to make sure that every developer has a path that allows them to work as efficiently and effectively as possible, whether that’s using NBEclipse, MS Visual Studio, or Vim. If you have any questions or comments on our utilities, we’d love to hear from you! Please drop a note in our comments below, or send us an email directly at sales@netburner.com.

Share this post

Subscribe to our Newsletter

Get monthly updates from our Learn Blog with the latest in IoT and Embedded technology news, trends, tutorial and best practices. Or just opt in for product change notifications.

1 thought on “Building Applications with NetBurner Command Line Tools

  1. I must admit that I don’t really like the Eclipse IDE, it feels a bit old, although its debugging tools are pretty good.

    Lately, I’ve been using VS Code for all kinds of back-end, front-end, and firmware development and have settled quite a bit, especially for autocompletion.

    I made a little base for using the netburner command line, it’s very basic and I don’t even know how to debug from VS Code … so I’ll use it as a text editor and continue to use Eclipse for more complex tasks.

    To achieve it I base myself on this tutorial: https://mcuoneclipse.com/2021/05/01/visual-studio-code-for-c-c-with-arm-cortex-m-part-1/

    Because I am not an expert in Cmake I did not use it as it comes in the tutorial, although it would be good if you had a tutorial on how to use it to be able to achieve this other tutorial https://medium.com/practical-coding/c- documentation-with-doxygen-cmake-sphinx-breathe-for-those-of-use-who-are-totally-lost-7d555386fe13

    For my base using VS Code I made the following files inside the .vscode folder. If you have any other settings to use VSCode, I would greatly appreciate it if you could provide it to me.

    tasks.json
    {
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    “version”: “2.0.0”,
    “tasks”: [
    {
    “type”: “shell”,
    “label”: “Build & Load Project”,
    “command”: “make -j load DEVIP=192.168.137.100”,
    “options”: {
    “cwd”: “${workspaceFolder}”
    },
    “group”: {
    “kind”: “build”,
    “isDefault”: true
    },
    “problemMatcher”: {
    “base”: “$gcc”,
    “fileLocation”: [
    “relative”,
    “${workspaceFolder}”
    ]
    }
    },
    {
    “type”: “shell”,
    “label”: “Build Project”,
    “command”: “make -j”,
    “options”: {
    “cwd”: “${workspaceFolder}”
    },
    “group”: “build”,
    “problemMatcher”: {
    “base”: “$gcc”,
    “fileLocation”: [
    “relative”,
    “${workspaceFolder}”
    ]
    }
    },
    {
    “type”: “shell”,
    “label”: “Clean Project”,
    “command”: “make clean”,
    “options”: {
    “cwd”: “${workspaceFolder}”
    },
    “group”: “build”,
    “problemMatcher”: {
    “base”: “$gcc”,
    “fileLocation”: [
    “relative”,
    “${workspaceFolder}”
    ]
    }
    },
    {
    “type”: “shell”,
    “label”: “Build Debug Project”,
    “command”: “make -j debug”,
    “options”: {
    “cwd”: “${workspaceFolder}”
    },
    “group”: “build”,
    “problemMatcher”: {
    “base”: “$gcc”,
    “fileLocation”: [
    “relative”,
    “${workspaceFolder}”
    ]
    }
    },
    ]
    }

    c_cpp_properties.json
    {
    “env”: {
    “NB_PATH”: “D:/Programas/nburn”
    },
    “configurations”: [
    {
    “name”: “Netburner MODM7”,
    “cStandard”: “c11”,
    “cppStandard”: “c++17”,
    “browse”: {
    “path”: [
    “${workspaceFolder}”,
    “${NB_PATH}”
    ],
    “limitSymbolsToIncludedHeaders”: false
    },
    “includePath”: [
    “${workspaceFolder}”,
    “${workspaceFolder}/src”,
    “${workspaceFolder}/**”,
    “${NB_PATH}/gcc/arm-unknown-eabi/sys-include/”,
    “${NB_PATH}/arch/cortex-m7/cpu/SAME70/include”,
    “${NB_PATH}/arch/cortex-m7/include”,
    “${NB_PATH}/gcc/arm-unknown-eabi/include”,
    “${NB_PATH}/gcc/arm-unknown-eabi/include/c++/8.1.0”,
    “${NB_PATH}/gcc/arm-unknown-eabi/include/c++/8.1.0/arm-unknown-eabi”,
    “${NB_PATH}/gcc/arm-unknown-eabi/include/c++/8.1.0/backward”,
    “${NB_PATH}/gcc/arm-unknown-eabi/sys-include/**”,
    “${NB_PATH}/gcc/lib/gcc/arm-unknown-eabi/8.1.0/include”,
    “${NB_PATH}/gcc/lib/gcc/arm-unknown-eabi/8.1.0/include-fixed”,
    “${NB_PATH}/libraries/include”,
    “${NB_PATH}/nbrtos/include”,
    “${NB_PATH}/platform/MODM7AE70/include”
    ]
    }
    ],
    “version”: 4
    }

Leave a Reply
Click to access the login or register cheese