MODRT1171

Introduction

This document provides the memory map and locations of reference materials for those who wish to add additional hardware to their NetBurner device.

The MODRT1171 is a high-performance System on Module built around the NXP i.MX RT1171 microprocessor. It is the recommended upgrade path and drop-in replacement for the MOD5441X, offering a faster processor, more memory, dual Gigabit Ethernet, and a larger application/file-system flash while preserving the familiar NetBurner development workflow and 100-pin dual-header form factor.

For detailed hardware and software guidance, two companion documents are provided as part of this platform reference:

• MODRT1171 Hardware Design Guide — for carrier board designers and system integrators.
• MODRT1171 Quick Reference Card — a condensed quick-reference card covering minimum connections, connector pinout, peripheral availability, and common code patterns.

Processor Information

The MODRT1171 uses the NXP i.MX RT1171 microprocessor (Arm Cortex-M7) running at 800MHz. The reference manual and datasheet provide in-depth information on the microprocessor, including register settings, bus configuration and timing information. It is located in the <nburn_install>\docs\NXP directory of your NetBurner installation.

Definitions

Definitions for the MIMXRT1171 can be found in arch/cortex-m7/cpu/MIMXRT11xx/include/MIMXRT1176_cm7.h

Datasheet and Pins

The datasheet for the MODRT1171 module includes information on connectors, signal names, and operational parameters. It is located on the MODRT1171 product page under Documents and Downloads.

An Excel spreadsheet of pin assignments is also available under the same Datasheet link.

NetBurner has created an interactive Pin Configurator tool for the MODRT1171 which is available online at https://netburner.com/NBDocs/PinConfigurator/MODRT1171.html, as well as in your NNDK installation under <nburn_install>\docs\NetBurner\Platform\PinConfigurator

You may also find pinconstant.h to be a useful reference.

Development Board Schematic

The DEV-MOD-105 development board schematic is located in the <nburn_install>\docs\NetBurner\platform\Schematics directory. This schematic can be used for design ideas in your own hardware implementation for power, RS-232, RS-485, and SD Flash card implementation.

MODRT1171 Platform General Information

The MODRT1171 uses the NXP i.MX RT1171 microcontroller. The reference manual and datasheet provide in-depth information on the processor, including register settings, bus configuration and timing information. The reference manual is located in the <nburn_install>\docs\NXP directory of your NetBurner installation.

• i.MX RT1171 Arm Cortex-M7 running at 800MHz
• 2MB on-chip SRAM (configurable ITCM/DTCM single-cycle TCM plus general purpose OCRAM)
• 64MB external SDRAM (2x W9825G6KH-5, 32-bit bus via SEMC) — application execution space
• 128MB SPI NAND application flash (Winbond W25N01GVZEIG) — stores the compressed application image and the file system
• 8Mbit (1MB) SPI NOR boot flash (GD25Q80CEIGR) — holds the boot monitor used by the boot ROM

The 128MB SPI NAND flash uses a Flash File System and is used for all application storage purposes:

• The standard NetBurner configuration, certificate and user parameter flash operate transparently through the file system.
• First erase block reserved for the file partition table. Note: If you need direct flash access, please contact NetBurner support.
• Application space varies by use case. Items that consume the total NAND space include: the compressed application image, file system overhead, certificates, configuration data, and any application-created files.

External Memory Bus

• The SEMC (Smart External Memory Controller) drives the on-module 64MB SDRAM
• Chip selects configurable anywhere in the external bus range

MODRT1171 EFFS-STD Flash File System

Overview

The MODRT1171 uses a 128 MB SPI NAND flash (Winbond W25N01GVZEIG) connected via the LPSPI2 peripheral. The flash is managed by EFFS-STD (Embedded Flash File System - Standard), which provides a structured file system with FAT-like directory and file operations. A separate 8 Mbit (1 MB) SPI NOR boot flash (GD25Q80CEIGR) holds the boot monitor used by the boot ROM and is not part of the file system.

Unlike older NetBurner platforms that use fixed compile-time memory regions (COMPCODEFLAGS) to partition flash between application firmware and file storage, the MODRT1171 uses a dynamic partition table stored in the first erase block of the SPI NAND flash. This partition table defines how the flash is divided, and all persistent data — including the application firmware image — is stored as files within the EFFS file system.

Because the medium is NAND (rather than the NOR flash used on some other modules), the driver works in terms of pages and uses the spare/out-of-band (OOB) area for bad-block management. The EFFS-STD configuration adapts automatically to the detected flash type.

Key Source Files

File	Purpose
arch/cortex-m7/cpu/MIMXRT11xx/include/effs_pt.h	Partition table and EFFS config struct definitions
arch/cortex-m7/cpu/MIMXRT11xx/source/EffsStd.cpp	Flash driver implementation and mount_std_fs()
arch/cortex-m7/cpu/MIMXRT11xx/source/nbpart.cpp	Partition table operations and Hamming ECC
platform/MODRT1171/source/hal_storage.cpp	HAL storage layer (config, certs, app, user params)
platform/MODRT1171/include/hal_platdefs.h	Maximum storage size constants
nbrtos/include/file/fsf.h	EFFS-STD API macros
nbrtos/include/file/fsm.h	FS_SPACE struct definition

---

Flash Memory Layout

The W25N01GVZEIG SPI NAND is organized as 2 KB pages (plus 64-byte OOB spare), 64 pages per 128 KB erase block, and 1024 erase blocks for a total of 128 MB. The logical layout is:

Block 0     +----------------------------------+
            | Partition Table (first block)     |  <- Hamming ECC protected
            | - sectorLenExp, totalSectors      |
            | - Up to 8 PartitionEntry structs  |
            | - 16 Hamming checksums            |
Block 1     +----------------------------------+
            | EFFS Partition (default: all      |
            |   remaining blocks)               |
            |                                   |
            | Effs_Cfg (first block of part)    |  <- Partition config
            | FAT + Directory blocks            |  <- EFFS metadata
            | Data blocks                       |  <- File storage
            |   A:/sys/files/config.xNN         |
            |   A:/sys/files/certs.xNN          |
            |   A:/sys/files/usrparam.xNN       |
            |   A:/sys/files/app.xNN            |
            |   (user application files)        |
            |                                   |
Block 1023  +----------------------------------+  <- 128 MB boundary

By default, a single EFFS partition spans from block 1 to the end of flash, and is marked as bootable. The first erase block is reserved for the partition table and is not part of any partition.

Important**: On the MODRT1171, the application firmware image is stored as a versioned file (A:/sys/files/app.xNN) inside the EFFS file system. There is no separate raw flash region for the application image as on older platforms such as the MOD5441X.

---

Partition Table Architecture

The partition table is defined in effs_pt.h and occupies the first erase block of SPI NAND.

PartitionTable Structure

struct PartitionTable {
    uint8_t bootExe[422];         // Reserved for boot executable
    uint8_t tableLenExp;          // Table length exponent (2^tableLenExp bytes)
    uint8_t sectorLenExp;         // Sector length exponent (e.g., 17 = 128 KB erase blocks)
    uint32_t totalSectors;        // Total sectors in device (MSB encoding for large values)
    PartitionEntry part[8];       // Up to 8 partition entries
    uint8_t csums[16];            // Hamming code checksums (one per 31-byte block)
};

On the MODRT1171, the default partition table uses a sectorLenExp of 17 (128 KB, matching the NAND erase-block size) and a totalSectors of 1024.

PartitionEntry Structure

struct PartitionEntry {
    uint32_t flags : 8;           // PARTITION_FLAG_INUSE (0x01), PARTITION_FLAG_BOOT (0x80)
    uint32_t sectorCount : 24;    // Number of sectors (MSB encoding for large values)
    uint32_t partitionType : 8;   // PARTITION_TYPE_EFFS (0x25)
    uint32_t firstSector : 24;    // Starting sector (MSB encoding for large values)
};

Partition types**: PARTITION_TYPE_EFFS (0x25) is the only type used by the NetBurner system. Other types (FAT12, FAT16, NTFS, Linux) are defined but reserved for future use.

MSB encoding**: When sectorCount or firstSector values exceed 2^23, the MSB is set and the value is encoded as (2^(exponent+4)) * mantissa, enabling representation of very large flash devices.

Error Protection

The partition table is protected by Hamming code checksums. Each 31-byte block of the table has an 8-bit checksum stored in the csums[] array. On read, validatePartitionTable() uses hamming_validateOrFix() to detect and correct single-bit errors. This protects against flash bit-rot and ensures the partition table remains valid over the device lifetime.

Partition Table Operations

All functions are in nbpart.cpp:

Function	Purpose
getPartitionTable(pt)	Read partition table from the first block and validate
createPartitionTable(pt, sectorLenExp, totalSectors)	Initialize an empty partition table
createPartitionEntry(pt, pte, startSector, sectorCount, type, bootable)	Create a new partition entry
createPartition(pt, pte)	Insert a partition entry (overlap-checked, sorted)
deletePartition(pt, partIdx)	Remove a partition entry
writePartitionTable(pt)	Compute checksums and write to flash
showPartitionTable(pt)	Debug print of partition table contents

---

EFFS Configuration per Partition

Each EFFS partition stores its configuration in an Effs_Cfg struct at the first block of the partition.

struct Effs_Cfg {
    uint16_t maxblock;        // Maximum number of usable blocks
    uint8_t sSizeExp;         // Sector size exponent (11 = 2048-byte NAND page)
    uint8_t blSizeExp;        // Block size exponent (17 = 131072-byte erase block)
    uint8_t dSizeExp;         // Descriptor (FAT+directory) size exponent (17 = 131072 bytes)
    uint8_t cacheSizeExp;     // Write cache size exponent (11 = 2048 bytes)
    uint8_t separatedir;      // Separate directory from FAT (1 for NAND flash)
    uint8_t csum;             // Hamming code checksum
};

Default configuration** (created by createDefaultFilesystem() in EffsStd.cpp). On NAND, the values are derived from the detected page and erase-block geometry:

Parameter	Value	Meaning
sSizeExp	11	2 KB sectors (one NAND page)
blSizeExp	17	128 KB blocks (erase unit)
dSizeExp	17	128 KB for FAT + directory
cacheSizeExp	11	2 KB write cache (one page)
separatedir	1	Directory kept separate from FAT (NAND)
maxblock	(calculated)	partitionSize / 128KB

The maxblock value determines how many 128 KB blocks are available for file data storage within the partition. For the default single-partition configuration on the 128 MB NAND, this is approximately 1022 blocks (after subtracting the partition-table block and EFFS metadata blocks).

---

File System Initialization

The EFFS file system is initialized automatically during the boot process, before UserMain() is called. Applications do not need to call any initialization functions.

Boot Sequence

HardwareInit()                          [hal_storage.cpp]
  └─ ConfigFlash()                      Configure LPSPI2 pins and init SPIFlash (AppFlash)
  └─ mount_std_fs()                     [EffsStd.cpp]
       ├─ fs_init()                     Initialize EFFS library
       ├─ getPartitionTable(&AppFlash_pt)  Read partition table (retry up to 5x)
       │   └─ (if invalid) createDefaultPartitionTable() + writePartitionTable()
       └─ For each EFFS partition with flags != 0:
            ├─ fs_getmem_flashdrive()   Calculate RAM requirements
            │   └─ (if 0) createDefaultFilesystem() and retry
            ├─ malloc(mem_size)         Allocate RAM for FS metadata
            ├─ fs_mountdrive(drv, ...)  Mount the partition as drive drv
            │   └─ (if fails) fs_format(drv)  Format and retry
            └─ Create /sys/ and /sys/files/ directories (on boot partitions)

After mounting, hal_bootPt is set to the index of the first bootable partition, and fs_chdrive(hal_bootPt) sets it as the default drive.

Flash Driver Architecture

Each partition is backed by a set of flash operation callbacks, registered in fs_phy_AF() (EffsStd.cpp):

• ReadFlash(data, block, blockrel, datalen) — Read data from a flash block (page-oriented on NAND)
• WriteFlash(data, block, relsector, size, relpos) — Write data to flash (with bounds checking)
• EraseFlash(block) — Erase a 128 KB block
• VerifyFlash(data, block, relsector, size, relpos) — Verify written data matches

All operations translate logical block/sector addresses to physical NAND page numbers using:

physPage = partitionStartPage + (block * pagesPerBlock) + (relSector * pagesPerSector)

Bounds checking ensures no operation can read or write outside the partition's page range. Because the device is NAND, the driver also performs bad-block detection (IsBadBlock()) and stores integrity information in each page's OOB spare area, so worn or factory-marked blocks are skipped automatically.

Since EFFS requires separate callback function pointers per drive, EffsStd.cpp generates 8 sets of wrapper functions (EraseFlash_0 through EraseFlash_7, etc.) that forward to a common implementation with the drive number as a parameter.

---

System File Storage (HAL Storage Layer)

The HAL storage layer (hal_storage.cpp) manages four categories of system data as versioned files in the A:/sys/files/ directory:

Storage Area	File Pattern	Max Size	Purpose
HalStore_Config	config.xNN	32 KB	JSON system configuration
HalStore_Cert	certs.xNN	2 MB	SSL/TLS certificate store
HalStore_UserParams	usrparam.xNN	16 KB	Application user parameters
HalStore_App	app.xNN	32 MB	Firmware application image

Version Suffix

Each file has a .xNN suffix where NN is a two-digit hex sequence number (00-FF). When a new version is saved:

1. HalStorage_FindLastVer() scans for the highest existing sequence number
2. The new file is created with sequence number = last + 1 (wrapping at 0xFF)
3. If insufficient free space, older versions are deleted starting from lastVer + 127 (opposite side of the circular sequence)

This versioning scheme provides safe atomic updates: if a write is interrupted (e.g., power loss), the previous version remains intact and will be loaded on the next boot.

Garbage Collection

Previous file versions are cleaned up by FlashErasePrevVersions(), which runs in the idle task (OSTaskIdle) approximately 2 seconds after boot. It keeps only the 2 most recent versions of each file type and deletes older ones.

HAL Storage API

Function	Purpose
HalStorage_Save(area, pData, len, offset)	Write a complete file (creates new version)
HalStorage_SavePartial(area, pData, len, offset)	Write partial data at an offset
HalStorage_Read(area, pData, len, offset)	Read from the latest version
HalStorage_Prepare(area, len, offset)	Open file for writing (with space management)
HalStorage_Finalize(area)	Close an open file handle
HalStorage_Erase(area, len, offset)	Delete all versions of a file
HalStorage_GetAllocated(area)	Get total usable space (free + used)
HalStorage_RemainingSpace(area)	Get free space on the boot partition
HalStorage_GetMaxAllocation(area)	Get per-area maximum size limit

---

File System Size and Statistics

Querying Free Space

Use fs_getfreespace() to get current space statistics for any mounted drive:

#include <file/fsf.h>
 
FS_SPACE fspace;
int rc = fs_getfreespace(driveNum, &fspace);
if (rc == FS_NOERR) {
    iprintf("Total: %lu bytes\r\n", fspace.total);
    iprintf("Free:  %lu bytes\r\n", fspace.free);
    iprintf("Used:  %lu bytes\r\n", fspace.used);
    iprintf("Bad:   %lu bytes\r\n", fspace.bad);
}

The FS_SPACE struct is defined in nbrtos/include/file/fsm.h:

typedef struct {
    unsigned long total;   // Total bytes available for file storage
    unsigned long free;    // Free bytes
    unsigned long used;    // Used bytes
    unsigned long bad;     // Bad sector bytes (unusable)
} FS_SPACE;

Storage Size Constants

Maximum storage sizes per area are defined in platform/MODRT1171/include/hal_platdefs.h:

Constant	Value	Description
PLAT_STORAGE_MAX_CONFIG_SIZE	0x8000 (32 KB)	Maximum config file size
PLAT_STORAGE_MAX_USERPARAMS_SIZE	0x4000 (16 KB)	Maximum user params size
PLAT_STORAGE_MAX_CERTSTORE_SIZE	0x200000 (2 MB)	Maximum certificate store size
PLAT_STORAGE_MAX_APP_SIZE	0x2000000 (32 MB)	Maximum application image size
PLAT_STORAGE_MAX_FILESYS_SIZE	0x1F00000 (31 MB)	Maximum file system size

Note: These constants are logical per-area maximums enforced by the HAL. The physical NAND is 128 MB, so the application image, file system, and user data all share the available NAND capacity minus the partition-table block and EFFS metadata.

Typical Space Budget (128 MB NAND, Default Single Partition)

Region	Size
Partition table (first erase block)	128 KB
Effs_Cfg (partition first block)	128 KB
EFFS metadata (FAT + directory)	varies with partition size
Usable file storage	**~127 MB**

The usable storage is shared between all files: system files (config, certs, app image, user params) and any application-created files.

---

Application Coexistence with System Storage

Single Shared File System

Applications and the system share the same EFFS file system on the boot partition. There is no need to create a separate file system for application data.

Directory layout on the boot partition:**

A:/
├── sys/
│   └── files/
│       ├── config.x00      ← System config (managed by HAL)
│       ├── certs.x00       ← SSL certificates (managed by HAL)
│       ├── usrparam.x00    ← User params (managed by HAL)
│       └── app.x00         ← Firmware image (managed by HAL)
├── app/                    ← Available for application use
├── usr/                    ← Available for application use
└── (any user directories)  ← Application can create freely

Rules for Application Code

1. Do NOT write to A:/sys/files/ directly. This directory is managed exclusively by the HAL storage layer. Use the SaveUserParameters() / GetUserParameters() API for persistent application settings, or the HAL storage API for other areas.

2. Use standard EFFS-STD API for application files. Applications can freely create directories and files anywhere outside of A:/sys/:

   // Create application directory
   fs_mkdir("mydata");
   fs_chdir("mydata");
    
   // Write a file
   FS_FILE *f = fs_open("sensor_log.dat", "w");
   if (f) {
       fs_write(buffer, 1, bufLen, f);
       fs_close(f);
   }

3. The file system is already mounted. On MODRT1171, mount_std_fs() runs during HardwareInit(), before UserMain() is called. Applications do not need to call EffsStart() or any other initialization function.
4. Thread safety. The EFFS-STD API is thread-safe. Each RTOS task is automatically tracked via FS_MULTI structures, and the fsm_* wrapper functions (which the fs_* macros resolve to) handle per-task locking internally. Multiple tasks can safely perform file operations concurrently.

5. Check available space before large writes. Since all data shares the same partition, a large application file could consume space needed for firmware updates or config saves. Use fs_getfreespace() to check:

   FS_SPACE fspace;
   if (fs_getfreespace(fs_getdrive(), &fspace) == FS_NOERR) {
       if (fspace.free >= requiredBytes) {
           // Safe to write
       }
   }

---

Comparison with the MOD5441X

The MODRT1171 is the upgrade path and replacement for the MOD5441X. Its partition-table approach is fundamentally different from the fixed-region approach used by the MOD5441X and other older NetBurner platforms (NANO54415, SB800EX, MODM7AE70, SBE70LC).

Feature	MODRT1171	MOD5441X
Processor	i.MX RT1171 Cortex-M7 @ 800 MHz	ColdFire MCF5441X @ 250 MHz
Flash Type	SPI NAND (128 MB)	Parallel NOR (32 MB)
Partitioning	Dynamic partition table in first block	Fixed COMPCODEFLAGS compile-time regions
App Image Storage	Stored as file in EFFS (A:/sys/files/app.xNN)	Dedicated raw flash region
Config/Certs	Versioned files in EFFS (*.xNN)	Dedicated flash sectors or EFFS files
Block Size	128 KB NAND erase block	128 KB
Sector Size	2 KB (NAND page)	1 KB
Max Partitions	8	1
Error Protection	Hamming codes on partition table and Effs_Cfg; NAND OOB bad-block management	None
FS Initialization	Automatic in HardwareInit() (before UserMain())	Application must call EffsStart()
FS Source Files	Built into platform library	Copied from examples/_common/EFFS/STD/

Key Differences for Application Developers

1. No EffsStart() call needed. On MODRT1171, the file system is mounted before UserMain() runs. On the MOD5441X, applications must explicitly call EffsStart("TaskName") to initialize and mount the file system.
2. No EFFS source files in application. On the MOD5441X, applications include source files from examples/_common/EFFS/STD/ (e.g., effsStdFlashDrv.cpp, fs_main.cpp, effs_std.cpp). On MODRT1171, all flash driver and mounting code is part of the platform library.
3. No COMPCODEFLAGS. The MOD5441X uses COMPCODEFLAGS in the makefile to define the boundary between application code and file system regions. On MODRT1171, this mechanism is not used — the partition table handles all flash region management.
4. File system always available. On MODRT1171, no special makefile flags or library includes are needed to use the file system. The PLAT_HAS_FILESYSTEM flag is always set.
5. Application image is a file. On MODRT1171, firmware updates write the application image as a file in the EFFS file system. On the MOD5441X, the application image is written directly to a raw flash region. This means MODRT1171 firmware updates use the same flash wear-leveling and bad-block management as regular file writes.

Boot Sequence

At power-up or reset, the application is decompressed from the NAND flash file system to external SDRAM, verified by checksum, and execution begins. If the checksum fails or the application crashes, the device will reboot to the Configuration Server to facilitate a recovery by downloading a new application.

If the application causes an issue in which continuous traps occur, or the state of the system is such the Configuration Server cannot run, a recovery hardware jumper procedure can be used to reset the device. See MODRT1171 for the full recovery procedure.

Note

It is always a good idea to have a serial port terminal connected to the boot/debug serial port to view status messages, or use the 'A' to abort the boot sequence command when prompted to abort application execution and boot to the Configuration Server.

UART Signals and Port Number Mapping

There can be a maximum of 11 serial ports configured on the device (LPUART1, 2, 3, 5, 6, 7, 8, 9, 10, 11 and 12; LPUART4 is reserved for the system debug console). Note that each signal pin on the microprocessor can be configured for up to several different functions, so to achieve the maximum number of serial ports some peripheral functions will be unavailable.

Please refer to the Communication peripheral table in the MODRT1171 Quick Reference Card for the UART header pin locations. Port number mapping for software API calls is defined in MODRT1171/include/serial_platdefs.h in the <nburn_install>\platform folder.

Hardware Design Guide

For carrier board designers and system integrators, the MODRT1171 Hardware Design Guide provides detailed guidance on power supply design, reset circuitry, Ethernet, analog interfaces, digital I/O voltage domains, communication interface routing, the SD card and display interfaces, layout guidelines, and a pin-to-peripheral quick reference.

Quick Reference

The MODRT1171 Quick Reference Card is a condensed quick-reference card covering the minimum connections required for operation, the full P1/P2 connector pinout, power and current-draw figures, a peripheral availability summary, voltage domains, common code patterns, and physical specifications.