{"id":19686023,"url":"https://github.com/nordicsemiconductor/nrf-intel-hex","last_synced_at":"2026-03-18T00:03:38.129Z","repository":{"id":24747795,"uuid":"102110446","full_name":"NordicSemiconductor/nrf-intel-hex","owner":"NordicSemiconductor","description":"Yet another parser for \"Intel HEX\" files.","archived":false,"fork":false,"pushed_at":"2023-11-28T12:33:14.000Z","size":680,"stargazers_count":28,"open_issues_count":2,"forks_count":7,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-23T05:17:39.560Z","etag":null,"topics":["hex","ihex","intel","parser"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NordicSemiconductor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-01T12:27:24.000Z","updated_at":"2025-02-26T19:24:16.000Z","dependencies_parsed_at":"2024-06-18T15:46:19.082Z","dependency_job_id":null,"html_url":"https://github.com/NordicSemiconductor/nrf-intel-hex","commit_stats":{"total_commits":59,"total_committers":7,"mean_commits":8.428571428571429,"dds":"0.10169491525423724","last_synced_commit":"43f62c6acdb9858d7434c593c923af24c8f07a21"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NordicSemiconductor%2Fnrf-intel-hex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NordicSemiconductor%2Fnrf-intel-hex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NordicSemiconductor%2Fnrf-intel-hex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NordicSemiconductor%2Fnrf-intel-hex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NordicSemiconductor","download_url":"https://codeload.github.com/NordicSemiconductor/nrf-intel-hex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251450656,"owners_count":21591407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hex","ihex","intel","parser"],"created_at":"2024-11-11T18:25:38.316Z","updated_at":"2025-10-27T13:11:48.914Z","avatar_url":"https://github.com/NordicSemiconductor.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# nrf-intel-hex\n\nYet another javascript parser/writer for \"[Intel HEX](https://en.wikipedia.org/wiki/Intel_HEX)\" files.\n\n[![Build Status](https://travis-ci.org/NordicSemiconductor/nrf-intel-hex.svg?branch=master)](https://travis-ci.org/NordicSemiconductor/nrf-intel-hex)\n\nThis is part of [Nordic Semiconductor](http://www.nordicsemi.com/)'s javascript tools to\ninterface with nRF SoCs and development kits. Although the HEX format is a *de facto*\nstandard and `nrf-intel-hex` should work on other hardware platforms, Nordic Semiconductor\ncannot offer support. This software is provided \"as is\".\n\n## Demo\n\nIf you have some .hex files around, and can copy-paste them, try the\n[interactive browser demo](https://nordicsemiconductor.github.io/nrf-intel-hex/demo.html).\n\n## Usage\n\nDo a `npm install nrf-intel-hex` or `yarn add nrf-intel-hex`, then\n\n```\nimport MemoryMap from 'nrf-intel-hex';\n\nlet intelHexString =\n    \":100000000102030405060708090A0B0C0D0E0F1068\\n\" +\n    \":00000001FF\";\n\nlet memMap = MemoryMap.fromHex(intelHexString);\n```\n\n`memMap` is a `MemoryMap`, a [`Map`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map)\nin which each key is a memory address offset, and each value is a\n[`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)\ncontaining binary data.\n\nFor contiguous data, that `Map` will have only one entry. For sparse data, it will have\nseveral entries, indexed by the start offset of each data block. Its keys are guaranteed\nto be in ascending order.\n\nIn order to write .hex records, provide a `Map` of `Uint8Array`s, where each key is the\nstart address of that block:\n\n```\nimport MemoryMap from 'nrf-intel-hex';\n\nlet memMap = new MemoryMap();\nlet bytes = new Uint8Array(....);\nmemMap.set(0x0FF80000, bytes); // The block with 'bytes' will start at offset 0x0FF80000\n\nlet string = memMap.asHexString();\n```\n\nThe return value will be a string of text containing all the records.\n\nThis module also provides some utility functions for handling `Map`s of `Uint8Array`s.\nCheck the full API documentation at https://nordicsemiconductor.github.io/nrf-intel-hex/doc/\n\n## Motivation\n\nThere are already other parsers/writers for HEX files (or, as the format is\n[formally known](http://microsym.com/editor/assets/intelhex.pdf), \"Hexadecimal\nObject File Format\". However, because [the original specification](http://microsym.com/editor/assets/intelhex.pdf)\nis (very) vague in some aspects, the existing implementations all have shortcomings.\n\nThis format was designed to «Allow the placement of code and data within [the]\n[address space](https://en.wikipedia.org/wiki/Address_space) of Intel processors».\nAltough the *common* use case is use the Intel HEX format for binary files,\nthere are also use cases for:\n\n* Specifying data which does not start at an address of zero (e.g. data to be\n  written at the end of a storage device)\n* Initializing peripherals by writing to their raw physical address\n* Specifying sparse (non-contiguous) data at some intervals\n\nAlso, the specification is vague about:\n\n* How records are separated\n* Whether addresses should be strictly ascending or not\n* Whether the file is meant for an 8-bit, 16-bit or 32-bit target\n  (whether to use 16-, 20- or 32-bit addresses respectively)\n* Whether there should be auto-detection of 8-, 16-, or 32-bit mode.\n* What happens if the same memory address appears twice in the same file.\n* What happens if there are 16- and 32-bit specific records in the same file.\n* What should be the behaviour of 8-bit address wrapping.\n* What should be the behaviour of 16-bit/32-bit address wrapping if/when\n  the addressing mode is not known.\n\nSome of the shortcomings in other parsers are:\n\n* Not handling data over the 64KiB boundary (only 16-bit addresses)\n* Naïvely assuming that the data is contiguous, or\n* Throwing an error if the data is sparse, or\n* Filling gaps in sparse data with `0x00`s or `0xFF`s\n\nThese assumptions might be right in the best case, but might cause destructive overwrites\nin the worst case.\n\n## Features\n\nWe wanted to cover the use cases at Nordic Semiconductor while clarifying behaviour and\novercoming the problems of other implementations. So, this **opinionated** implementation\nhas the following behaviour for parsing:\n\n* Allows for both uppercase and lowercase hexadecimal characters\n* Allows for `\\n`, `\\r`, `\\r\\n` and empty record separators\n* Does not assume that data is given in records with strictly ascending addresses;\n  out-of-order records create contiguous blocks of data.\n* Does not assume contiguous data blocks, and so can return more than one block of binary\n  data.\n* Silently ignores 0x03 and 0x05 type records (the ones which would reset the program\n  counter CPU registers - CS+IP in 16-bit mode, or EIP in 32-bit mode).\n* Records for 20-bit and 32-bit address offsets (types 0x02 and 0x04) can be handled at\n  the same time, but only the last one has effect.\n* Records which might wrap over the low 0xFFFF address will throw an exception. Altough\n  the spec calls for handling wrapping data over in 16- or 32-bit mode, not knowing the\n  expected behaviour in 8-bit mode, and not knowing which mode a file refers to, makes\n  it impossible to implement wrapping consistenly.\n\nThe behaviour for writing .hex format is stricter and predictable, in line with the\n[robustness principle](https://en.wikipedia.org/wiki/Robustness_principle):\n\n* Records have strictly ascending addresses.\n* No 0x03 nor 0x05 records are generated.\n* 32-bit mode is assumed. 0x02 records (16-bit mode segment offsets) are not used.\n* A 0x04 record (32-bit linear address offset) is always generated before the first\n  data record, even if the address of the first data record is 0x0.\n* No byte wrapping at 0xFFFF.\n* Default of 16 data bytes per record.\n* `\\n` is used as a record separator.\n* Throws an error if there is data over 0xFFFFFFFF (4GiB)\n\n### Compatibility\n\n`nrf-intel-hex` relies on ES2015, [`Map`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map),\n[`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) and\n[`String.prototype.padStart`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/padStart).\n\nIt will work out of the box in a Node.js version 8 (or higher), and in all major modern browsers\n(starting with Edge v15, Chrome/Chromium v57, Firefox v52, Safari v10). Node.js version 6\nrequires a `String.prototype.padStart` shim.\n\nWith proper ES2015→ES5 transpiling and shims, is *should* work in a nodejs environment as old\nas version 4, and in all major browsers (as old as Edge v12, Chrome/Chromium v38,\nFirefox v48, Safari v9).\n\n### TODO\n\nSome features that would be nice to have, but that are not needed for the current\nuse cases yet:\n\n* Stream mode: allow to start parsing a byte stream (e.g. file or network socket), and\n  emit data blocks of a given size when appropiate (e.g. when more than N contiguous byes have been parsed, or when jumping to a different memory address section). This is not a\n  priority, as our current use case for .hex files does not involve more than 1MiB of data.\n* Allow for some behaviour to be turned on/off\n* Allow for less-strict parsing (allow non-canonical comments in the input data)\n* Stricter treatment of 16- and 32-bit modes. Do not allow mixing records from both modes.\n* Stream mode for the writer: return a Generator or an Iterator, and output the records as\n  they are being requested.\n\n## Further reference\n\n* https://en.wikipedia.org/wiki/Intel_HEX\n* http://microsym.com/editor/assets/intelhex.pdf\n* http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.faqs/ka9903.html\n\n## Legal\n\nDistrubuted under a BSD-3 license. See the `LICENSE` file for details.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnordicsemiconductor%2Fnrf-intel-hex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnordicsemiconductor%2Fnrf-intel-hex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnordicsemiconductor%2Fnrf-intel-hex/lists"}