nrf-intel-hex

Yet another javascript parser/writer for “Intel HEX” files.

Build Status

This is part of Nordic Semiconductor’s javascript tools to interface with nRF SoCs and development kits. Although the HEX format is a de facto standard and nrf-intel-hex should work on other hardware platforms, Nordic Semiconductor cannot offer support. This software is provided “as is”.

Demo

If you have some .hex files around, and can copy-paste them, try the interactive browser demo.

Usage

Do a npm install nrf-intel-hex or yarn add nrf-intel-hex, then

import MemoryMap from 'nrf-intel-hex';

let intelHexString =
    ":100000000102030405060708090A0B0C0D0E0F1068\n" +
    ":00000001FF";

let memMap = MemoryMap.fromHex(intelHexString);

memMap is a MemoryMap, a Map in which each key is a memory address offset, and each value is a Uint8Array containing binary data.

For contiguous data, that Map will have only one entry. For sparse data, it will have several entries, indexed by the start offset of each data block. Its keys are guaranteed to be in ascending order.

In order to write .hex records, provide a Map of Uint8Arrays, where each key is the start address of that block:

import MemoryMap from 'nrf-intel-hex';

let memMap = new MemoryMap();
let bytes = new Uint8Array(....);
memMap.set(0x0FF80000, bytes); // The block with 'bytes' will start at offset 0x0FF80000

let string = memMap.asHexString();

The return value will be a string of text containing all the records.

This module also provides some utility functions for handling Maps of Uint8Arrays. Check the full API documentation at https://nordicsemiconductor.github.io/nrf-intel-hex/doc/

Motivation

There are already other parsers/writers for HEX files (or, as the format is formally known, “Hexadecimal Object File Format”. However, because the original specification is (very) vague in some aspects, the existing implementations all have shortcomings.

This format was designed to «Allow the placement of code and data within [the] address space of Intel processors». Altough the common use case is use the Intel HEX format for binary files, there are also use cases for:

Also, the specification is vague about:

Some of the shortcomings in other parsers are:

These assumptions might be right in the best case, but might cause destructive overwrites in the worst case.

Features

We wanted to cover the use cases at Nordic Semiconductor while clarifying behaviour and overcoming the problems of other implementations. So, this opinionated implementation has the following behaviour for parsing:

The behaviour for writing .hex format is stricter and predictable, in line with the robustness principle:

Compatibility

nrf-intel-hex relies on ES2015, Map, Uint8Array and String.prototype.padStart.

It will work out of the box in a Node.js version 8 (or higher), and in all major modern browsers (starting with Edge v15, Chrome/Chromium v57, Firefox v52, Safari v10). Node.js version 6 requires a String.prototype.padStart shim.

With proper ES2015→ES5 transpiling and shims, is should work in a nodejs environment as old as version 4, and in all major browsers (as old as Edge v12, Chrome/Chromium v38, Firefox v48, Safari v9).

TODO

Some features that would be nice to have, but that are not needed for the current use cases yet:

Further reference

Distrubuted under a BSD-3 license. See the LICENSE file for details.

This site is open source. Improve this page.