Upgrading From a MOD52xx SOM to the ARM MODM7AE70

MODM7AE70 100 ARM powered IoT System on Module with Ethernet Jack

Why Upgrade?

The first question any developer or engineer worth their salt is going to ask when evaluating whether or not to upgrade to a different platform is, “Why?”

The NetBurner MOD52xx system on modules (SOMs) are still active products with no current plans for end-of-life. The 2.9.x revision tool chain is alive and well and is maintained in parallel with the newer 3.x tool chain, so the question in this case is a valid one. There are several benefits that your applications can take advantage when upgrading to the MODM7AE70. Let’s take a minute to go through the list.

Hardware Performance and Cost

One of the biggest factors in deciding whether or not to upgrade to a new module will inevitably be cost. In many cases, upgrading to a newer module can often increase the cost of a design, and power consumption generally goes up when adding a faster processor with more peripherals. In both cases, the MODM7AE70 flies in the face of convention. When compared to the MOD52xx platforms, the MODM7AE70 benefits from the following:

  • Lower SOM cost
    • In some cases, as much as 40%. 
  • Much higher performance
    • In addition to overall performance, this can be very useful as encryption key sizes continue to get larger and affect negotiation time. 
  • Hardware floating point math
  • Lower power requirements

Configuration and Application Updates 

NetBurner’s latest tools, NNDK 3.x, have added a host of new options to configure and update your devices. Gone are the days of relying on a platform dependent utility to get the job done. It is still a valid method, of course, but there are several new options to choose from. Here is the full rundown.

  • The new IoT configuration system enables each SOM to handle its own configuration and code updates. There are many configuration options, all of which can be enabled/disabled and password protected based on your application requirement.
  • Device discovery, configuration, and code updates are now platform independent and do not require any OS specific utilities. However, If you prefer a utility, they are available as well.
  • Devices can be discovered by going to “discover.netburner.com”.
    • For those that don’t wish to use a public utility (or can’t), we provide everything needed to setup a private server that can be used to serve the same functionality.
  • Applications can be updated from any web browser, the NBUpdate utility, NBEclipse, WGET, and through the device’s serial port.
  • Device configuration can now be done with a JSON object. These objects can be saved and uploaded through a web interface, making configuration in a production environment much easier and faster.
  • Developers can easily create their own application specific configuration interface for branding or expansion.

Development Tools 

  • NBEclipse has been updated to use Eclipse 2018-12
    • Among other benefits, it allows for makefile generation for automated build systems. 
  • Updated GCC compiler to 8.1
    • As one of several benefits, it utilizes all available processor cores to greatly reduce build times.
    • Note that this version of GCC is noticeably more strict than the previous version we released. This may cause some previous “warnings” to be upgraded to “errors”.

System 

  • Increased the number of RTOS tasks
    • Default is 256, but can be increased as a configuration option. 
  • Increased the number of TCP sockets
    • Default is 256, but can be increased as a configuration option. 

Upgrade Overview 

Now that we know the reasons to upgrade, let us talk about how to go about doing it. In our customer beta tests, upgrades have taken from as little as an hour to as long as a few days. The time will depend on the complexity of the application, how many peripherals are utilized, and the structure of the application code itself. The goal of this document is to provide guidance to make this process as easy as possible.

Upgrading from a Tools Release Prior to 2.8.0

In this document the term “2.x” refers to releases 2.8.0 and above. Release 2.7.7 was the last tools release for the IPv4 only stack. Please refer to the migration documents  for the single IPv4 stack to the dual IPv4/IPv6 stack for additional porting changes, such as the IPADDR type. 

Hardware and Pin Comparison

Our product lines were designed from the beginning with upgrading in mind. Mechanically, the MODM7AE70 is identical to the MOD5272, MOD5270, and MOD5282. On the MOD5234 and MOD5441X, the critical dimensions of the Ethernet jack, male header pins and mounting holes are identical. However, the tail end of the PCB (the end opposite the Ethernet jack), is slightly longer. If a MOD5234 is currently in your design, the MODM7AE70 will fit as well.

We have created a pin comparison page  for the MOD52xx SOMs vs the MODM7AE70.  You should find that most, if not all the signals in your design are compatible. If you are using the external address and data bus, we recommend contacting support. Although the signals are the compatible, external bus hardware can vary in its implementation.

If you are using the NANO54415, MO5441X, or SB800EX, you can easily upgrade to the 3.x tools.

Upgrade Topics

Device Discovery

In previous versions of our tools, locating and configuring your device required the use of IPSetup. In 3.x, we’ve introduced several new ways to do this.

If both your computer and the NetBurner device have Internet connectivity, open a web browser and go to the site discover.netburner.com. This will list all the NetBurner devices you have access to on your network. If you use this mechanism for your customers, you can create your own discovery server and use that address instead. For example, www.mydiscoveryserver.com. For more information on how to do this, please feel free to contact us.

discover.netburner.com

Screenshot of discover.netburner.com

If you are connected directly to the NetBurner device and/or do not have Internet connectivity, use the LocalDiscover utility located in your \nburn\pcbin directory.

Screenshot of the LocalDiscover Utility

Lastly, although IPSetup is deprecated, you should still be able to use it to locate the device’s IP address, although it can no longer be used to configure the device.

Device Configuration

Once you have located your device, click on the Config link. Alternatively, if you already know the device’s IP address, you can navigate to <device IP address>:20034 from any web browser.

This will open a web page that enables you to view or modify the system settings. The screen shot below shows the default config server (you can customize it ) with the IPv4 section open. You can also configure parameters such as boot and IPv6. The App Data section is available for any data you wish to present from your application.

The device configuration page is accessible from the web browser.

Screenshot of Device Configuration Page

NBEclipse

The latest NBEclipse versions are very similar to those in the 2.x releases. However, for compatibility reasons some changes to the structure of a project were required.  In 2.x, the source files, HTML folder and build files were all in the project root folder, and the “release” folder contained the application image:

NBEclipse 2.x

New to 3.x is how the system library is handled. In 2.x, only one library existed for all projects, named netburner.a. This created an issue for customers who required library modifications that were different for each project. In 3.x we addressed this issue. Each project now has its own copy of the system library, named libnetburner.a, which is unique to that project.

A 3.x NBEclipse project has the following format with respect to the project root folder:

  • Source files are located in a folder named src.
  • Web content is still located in a folder named html.
  • In addition to the application image, the release folder now has 2 sub folders: nblibs and src. The nblibs folder contains the project’s compiled system library. The src folder contains the project’s compiled object files.

NBEclipse 3.x

Application Image File Format

The 2.x tools, both with NBEclipse and command line, produced a Motorola S-Record .S19 file. In 3.x the file format has changed to a much smaller binary format with file extension .bin.  In the current 3.3 release, a ColdFire 5441x platform project will build both .bin and .s19. However, the default, which we recommend, is the .bin file.

Application Differences: Include Files, Initialization and Basic Types

In this section we will illustrate the differences in a simple network application. These are:

  • The common header files to include
  • The initialization sequence in UserMain()
  • The web server initialization functions have changed from StartHTTP() and StartHTTPS() to StartHttp() and StartHttps() respectively

A Simple 2.x Application

An Equivalent 3.x Application

It should also be noted that the location of the source files has changed. In 2.x, all system files were found in \<nndk_install>\system and \<nndk_install>\include. In 3.x, this has moved to \<nndk_install>\nbrtos\system and \<nndk_install>\nbrtos\include, respectively.

Header Files

The common 2.x header files such as:

#include <startnet.h>
#include <autoupdate.h>
#include <dhcpclient.h>
#include <smarttrap.h>
#include <taskmon.h>
#include <NetworkDebug.h>
#include <ucos.h>

Are replaced with:

#include <nbrtos.h> // Replaces ucos.h specifically
#include <iosys.h>
#include <init.h>

Initialization

The 2.x initialization functions:

    
    InitializeStack();
    GetDHCPAddressIfNecessary();
    OSChangePrio(MAIN_PRIO);
    EnableAutoUpdate();
    StartHTTP();
    EnableTaskMonitor();

    #ifndef _DEBUG
    EnableSmartTraps();
    #endif

    #ifdef _DEBUG
    InitializeNetworkGDB_and_Wait();
    #endif

Are all replaced with:

init();

Basic Variable Types

The basic types have changed to be more descriptive. The changes are shown below for 2.x to 3.x:

2.x Data Type 3.x Data Type
BYTE uint8_t
PBYTE *uint8_t
SHORT int16_t
PSHORT *int16_t
WORD uint16_t
PWORD *uint16_t
LONG int32_t
PLONG *int32_t
DWORD uint32_t
PDWORD *uint32_t

Please note that the type int is still valid and represents int32_t on current platforms.

The NetBurner RTOS

The 3.x NBRTOS is very similar to the 2.x RTOS with significant enhancements. These include dramatic performance improvements and significantly increasing the number of tasks. In general, RTOS features such as semaphores, mailboxes, critical sections, FIFOs, and queues are now C++ objects. Any code changes should be minor but will include changing the explicit functions calls to a call to the object’s member function. For example, to initialize a semaphore:

For example, initializing a semaphore:

OSSemInit(&MySemaphore, 0);

becomes:

MySemaphore.Init();

The library API documentation  provides a description of each member function and its optional/default parameter values. Also, in NBEclipse, as you type the name of the object, tips will appear showing all the member functions and their default parameters.

The example below is located in the \nburn\examples\RTOS folder

In 2.x

void UserMain( void *pd )
{
    InitializeStack();
    GetDHCPAddressIfNecessary();
    OSChangePrio(MAIN_PRIO);
    EnableAutoUpdate();
    EnableTaskMonitor();

    #ifndef _DEBUG
    EnableSmartTraps();
    #endif

    #ifdef _DEBUG
    InitializeNetworkGDB_and_Wait();
    #endif

    OSSemInit(&MySemaphore, 0);
    OSSimpleTaskCreatewName( MyTask, MAIN_PRIO + 1, "Semaphore");

    while ( 1 )
    {
        iprintf(">>> UserMain: Pending on Semaphore from MyTask\r\n");
        OSSemPend(&MySemaphore, 0);
        iprintf("<<< UserMain: Semaphore was posted from MyTask!\r\n\r\n");
    }
}

In 3.x

OS_SEM MySemaphore;

void UserMain(void *pd)
{
    init();
    MySemaphore.Init();
    OSSimpleTaskCreatewName(MyTask, MAIN_PRIO + 1, "Semaphore");

    while (1)
    {
        iprintf(">>> UserMain: Pending on Semaphore from MyTask\r\n");
        MySemaphore.Pend();
        iprintf("<<< UserMain: Semaphore was posted from MyTask!\r\n\r\n");
    }
}

Handling IP Addresses

The functionality of the IPADDR object is covered in detail in the NetBurner Programmers Guide IPv4/IPv6 dual stack section. However, we want to cover some of the formatting here since it can make your updated code much cleaner.

The IPADDR type is based on two objects: IPADDR4 and IPADDR6. Whenever possible it is preferable to use the IPADDR type, which can hold either an IPv4 or IPv6 address. When using the IPADDR type, the correct member function will automatically be called, whether the underlying type is IPv4 or IPv6. For example, to set the value of an IP address you can use the SetFromAscii() member function:

void UserMain(void * pd)
{
    init();
    WaitForActiveNetwork(TICKS_PER_SECOND * 5); 
    StartHttp();

    IPADDR myIPv4;
    IPADDR myIPv6;

    myIPv4.SetFromAscii("172.1.2.3");
    myIPv6.SetFromAscii("fe80::203:f4ff:fe0b:8481");

    iprintf("myIPv4: %I\r\n", myIPv4);
    iprintf("myIPv6: %I\r\n", myIPv6);


    iprintf("Application %s started\r\n",AppName );
    while (1)
    {
        OSTimeDly(TICKS_PER_SECOND);
    }
}

The corresponding output is:

Primary network interface configured for DHCP
MAC Address = 00:03:f4:0b:84:8f
Type “A” to abort boot
myIPv4: 172.1.2.3
myIPv6: fe80::203:f4ff:fe0b:8481
Application AppWiz started

There are a few things to take note of from this example:

  • The two variables, myIPv4 and myIPv6, are both of type IPADDR.
  • The same member function name, SetFromAscii(), is used to set each type of address. This will set the IPADDR address type to either IPv4 or IPv6. For those interested, SetFromAscii4() or SetFromAscii6() will be called in the library code depending on the type of IP address provided. In fact, there will be a ‘4’ and ‘6’ version of nearly all IPADDR member functions.
  • The printf() function to display the IP address uses the %I format specifier. More on that below.

NetBurner IPADDR Format Specifiers

The printf() functions have additional format specifiers to make it easier to display IP address information. These specifiers are applicable to all the printf() type functions, such as iprintf(), printf(), fdprintf(), sprintf(), etc. The added format specifiers are:

%I Parameter is an IPADDR object, either IPv4 or IPv6
%hI Parameter is an IPADDR4 object, IPv4

Configuration/Interface IPADDR Objects

When manipulating or displaying an IP address object, it is important to know whether it is an IPADDR, or an IPADDR4. There are some protocols which support only IPv4, and in those cases the object type is IPADDR4. In this case, functions are called explicitly with the ‘4’ version. For example, GetHostByName4().

The \nburn\examples\ShowInterfaces example is a great resource to examine for handling configuration record settings. For example, the IPv4 settings in the configuration record are of type IPADDR4, and helper functions such as InterfaceIP() are used to display their values.

Checking for a NULL value, and Setting a NULL value

In IPv4, the address could be considered a 32-bit unsigned integer, and settings or checking for a null/zero value was a comparison to 0. For an object the member functions SetNull() and IsNull() are used. Here are some examples for an IPADDR variable named myIpAddr:

Set a null value: myIpAddr.SetNull();
Check for a null value: myIpAddr.IsNull();

You can also specify a null address as a static IPADDR::NullIP(). For example:

DNSResult = GetHostByName( serverName, &serverIp, IPADDR::NullIP(),
    TICKS_PER_SECOND * 20 );

The null IP value tells the function to use a random source port number.

Wrapping Up

That’s about it! Hopefully this guide provides you with a clear picture of the steps that will be required to update from a MOD52xx module to our newer module, the MODM7AE70. If you have any other questions or concerns about the upgrade, please feel free to contact us directly at sales@netburner.com, or leave us a comment below.

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.

Leave a Reply
Click to access the login or register cheese