{"id":2074,"library":"intelhex","title":"IntelHex Library","description":"IntelHex is a Python library for manipulating Intel HEX files, which are commonly used for programming microcontrollers and memory devices. It provides functionalities to read, write, parse, modify, and analyze HEX file data. The current version is 2.3.0, with a release cadence that addresses bug fixes and introduces new API features as needed.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/python-intelhex/intelhex","tags":["hex","intelhex","firmware","embedded","microcontroller"],"install":[{"cmd":"pip install intelhex","lang":"bash","label":"Install IntelHex"}],"dependencies":[],"imports":[{"symbol":"IntelHex","correct":"from intelhex import IntelHex"}],"quickstart":{"code":"import tempfile\nimport os\nfrom intelhex import IntelHex\n\n# Create a dummy HEX file content\nhex_content = \"\"\"\n:10010000214601360121470136007E012321460119FF\n:100110002146017E17C20001FF50013001360120202F\n:00000001FF\n\"\"\".strip()\n\n# Use a temporary file for demonstration\nwith tempfile.TemporaryDirectory() as tmpdir:\n    hex_filepath = os.path.join(tmpdir, \"example.hex\")\n\n    with open(hex_filepath, \"w\") as f:\n        f.write(hex_content)\n\n    print(f\"Created dummy hex file at: {hex_filepath}\")\n\n    # Load the Intel HEX file\n    ih = IntelHex()\n    ih.loadhex(hex_filepath)\n\n    print(f\"Loaded hex file with {len(ih.segments())} segments.\")\n\n    # Read a byte at a specific address\n    address_to_read = 0x100\n    byte_value = ih[address_to_read]\n    print(f\"Byte at {hex(address_to_read)}: {hex(byte_value)}\")\n\n    # Modify a byte\n    ih[0x100] = 0xAA\n    print(f\"Modified byte at {hex(address_to_read)} to: {hex(ih[address_to_read])}\")\n\n    # Write the modified data to a new HEX file\n    output_hex_filepath = os.path.join(tmpdir, \"modified.hex\")\n    # Using eolstyle='LF' explicitly (see warnings)\n    ih.write_hex_file(output_hex_filepath, byte_count=16, eolstyle='LF')\n    print(f\"Modified hex file written to: {output_hex_filepath}\")\n\n    # Basic verification\n    with open(output_hex_filepath, \"r\") as f:\n        modified_content = f.read()\n        if \":10010000AA4601360121470136007E012321460127\" in modified_content:\n            print(\"Verification successful: Modified byte found in output.\")\n        else:\n            print(\"Verification failed.\")","lang":"python","description":"This quickstart demonstrates how to load an Intel HEX file, read and modify data, and then write the changes back to a new HEX file. It uses a temporary directory for file operations and highlights the use of `eolstyle` during file writing, which is crucial for cross-platform compatibility."},"warnings":[{"fix":"If you require strict separation of all non-overlapping segments, explicitly set `min_gap=0` when calling `ih.segments(min_gap=0)`. Adjust `min_gap` as needed to control segment consolidation behavior.","message":"In IntelHex v2.3.0, the `IntelHex.segments()` method introduced a new optional parameter `min_gap` with a default value of `1`. This means segments with gaps smaller than 1 byte (i.e., touching segments) will now be consolidated into a single segment by default, which changes the behavior compared to previous versions that strictly separated all non-overlapping segments.","severity":"gotcha","affected_versions":">=2.3.0"},{"fix":"For new projects or existing Python 3 projects, always use `intelhex` version 2.0 or newer. For Python 2 projects, using `intelhex` >= 2.0 also provides better cross-compatibility and bug fixes.","message":"Versions of IntelHex prior to 2.0 had significant Python 3 compatibility issues or required the `2to3` tool. While improvements were made in 2.0, ongoing fixes for Python 3 compatibility, especially for command-line scripts, continued through versions 2.1 and 2.2.","severity":"deprecated","affected_versions":"<2.0"},{"fix":"Always explicitly set the `eolstyle` parameter to `'CRLF'` or `'LF'` when writing HEX files, e.g., `ih.write_hex_file(filepath, eolstyle='CRLF')`, to ensure consistent line endings compatible with your target environment.","message":"When writing Intel HEX files using `IntelHex.write_hex_file()` (available since v2.2) or `IntelHex.tofile()` with `format='hex'` (available since v2.3.0), the default `eolstyle` is 'native' (OS-dependent). This can lead to issues if the target device or programmer expects specific line endings (e.g., CRLF for Windows-style, LF for Unix-style) regardless of the host OS.","severity":"gotcha","affected_versions":">=2.2"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}