# mcbootflash
[](https://bessman.github.io/mcbootflash/)
[](https://pypi.org/project/mcbootflash/)
[](https://mit-license.org/)
## What
Mcbootflash is a tool for flashing firmware to 16-bit Microchip MCUs and DSCs
from the PIC24 and dsPIC33 device families, which are running a
[bootloader](https://www.microchip.com/en-us/software-library/16-bit-bootloader)
generated by the MPLAB Code Configurator tool.
Mcbootflash is intended to be a drop-in replacement for Microchip's official tool, the
Unified Bootloader Host Application (UBHA).
## Why
Mcbootflash is:
### Scriptable
As a command-line application, mcbootflash is easily scriptable.
### Extensible
In addition to its command-line interface, mcbootflash can be used as a library by
applications wanting to implement firmware flashing as part of a larger suite of
features.
### Free and Open Source
Mcbootflash is distributed under the MIT license.
## Installation
Stand-alone executables for Linux, Mac, and Windows are available from the Github
[release page](https://github.com/bessman/mcbootflash/releases/latest).
Mcbootflash can also be installed from PyPI:
`pip install mcbootflash`
## Usage
Mcbootflash can be used as both a command-line application and a library.
### Command-line
```shellsession
$ mcbootflash --help
usage: mcbootflash [-h] -p PORT -b BAUDRATE [--timeout TIMEOUT] [--checksum] [--reset] [--debug] [--quiet] [--version] hexfile
mcbootflash is a tool for flashing firmware to 16-bit Microchip MCUs and DSCs from the PIC24 and dsPIC33 device families, which are running a bootloader generated by the MPLAB Code Configurator tool.
positional arguments:
hexfile an Intel HEX file containing application firmware
options:
-h, --help show this help message and exit
-p, --port PORT serial port connected to the device you want to flash
-b, --baudrate BAUDRATE
symbol rate of device's serial bus
--timeout TIMEOUT try to read data from the bus for this many seconds before giving up
--checksum verify flashed data by checksumming after write
--reset reset device after flashing is complete
--debug print debug messages
--quiet suppress output
--version show program's version number and exit
```
#### Example
```shellsession
$ mcbootflash --port /dev/ttyUSB0 --baudrate 460800 firmware.hex
Connecting to bootloader...
Erasing program area...
100% 162.0 KiB |######################################| Elapsed Time: 0:00:01
Flashing firmware.hex...
100% 98.8 KiB |#######################################| Elapsed Time: 0:00:06
Self verify OK
```
### Library
When using mcbootflash as a library, typical workflow looks something like this:
``` py
import mcbootflash as bf
import serial
# Connect to a device in bootloader mode.
connection = serial.Serial(port=<PORT>, baudrate=<BAUDRATE>, timeout=<TIMEOUT>)
# Query its attributes.
bootattrs = bf.get_boot_attrs(connection)
# Load the firmware image and split it into chunks.
total_bytes, chunks = bf.chunked(hexfile=<HEXFILE_PATH_STRING>, bootattrs)
# Erase the device's program memory area.
bf.erase_flash(connection, bootattrs.memory_range, bootattrs.erase_size)
# Write the firmware chunks to the bootloader in a loop.
for chunk in chunks:
bf.write_flash(connection, chunk)
# Optionally, check that the write is OK by checksumming.
bf.checksum(connection, chunk)
# At this point, you may want to give an indication of the flashing progress,
# like updating a progress bar.
# Verify that the new application is detected.
bf.self_verify(connection)
```
See also the [API Reference](https://bessman.github.io/mcbootflash/api/).
Raw data
{
"_id": null,
"home_page": null,
"name": "mcbootflash",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "firmware, flashing, bootloader, serial, uart, microchip, pic24, dspic33, 16-bit",
"author": null,
"author_email": "Alexander Bessman <alexander.bessman@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9d/d1/1e90584fae25c20c79bdf8546f4fbce206d8b854b157fb5ffe941094cf58/mcbootflash-10.1.0.tar.gz",
"platform": null,
"description": "# mcbootflash\n\n\n[](https://bessman.github.io/mcbootflash/)\n[](https://pypi.org/project/mcbootflash/)\n[](https://mit-license.org/)\n\n## What\n\nMcbootflash is a tool for flashing firmware to 16-bit Microchip MCUs and DSCs\nfrom the PIC24 and dsPIC33 device families, which are running a\n[bootloader](https://www.microchip.com/en-us/software-library/16-bit-bootloader)\ngenerated by the MPLAB Code Configurator tool.\n\nMcbootflash is intended to be a drop-in replacement for Microchip's official tool, the\nUnified Bootloader Host Application (UBHA).\n\n## Why\n\nMcbootflash is:\n\n### Scriptable\n\nAs a command-line application, mcbootflash is easily scriptable.\n\n### Extensible\n\nIn addition to its command-line interface, mcbootflash can be used as a library by\napplications wanting to implement firmware flashing as part of a larger suite of\nfeatures.\n\n### Free and Open Source\n\nMcbootflash is distributed under the MIT license.\n\n## Installation\n\nStand-alone executables for Linux, Mac, and Windows are available from the Github\n[release page](https://github.com/bessman/mcbootflash/releases/latest).\n\nMcbootflash can also be installed from PyPI:\n\n`pip install mcbootflash`\n\n## Usage\n\nMcbootflash can be used as both a command-line application and a library.\n\n### Command-line\n\n```shellsession\n$ mcbootflash --help\nusage: mcbootflash [-h] -p PORT -b BAUDRATE [--timeout TIMEOUT] [--checksum] [--reset] [--debug] [--quiet] [--version] hexfile\n\nmcbootflash is a tool for flashing firmware to 16-bit Microchip MCUs and DSCs from the PIC24 and dsPIC33 device families, which are running a bootloader generated by the MPLAB Code Configurator tool.\n\npositional arguments:\n hexfile an Intel HEX file containing application firmware\n\noptions:\n -h, --help show this help message and exit\n -p, --port PORT serial port connected to the device you want to flash\n -b, --baudrate BAUDRATE\n symbol rate of device's serial bus\n --timeout TIMEOUT try to read data from the bus for this many seconds before giving up\n --checksum verify flashed data by checksumming after write\n --reset reset device after flashing is complete\n --debug print debug messages\n --quiet suppress output\n --version show program's version number and exit\n```\n\n#### Example\n\n```shellsession\n$ mcbootflash --port /dev/ttyUSB0 --baudrate 460800 firmware.hex\nConnecting to bootloader...\nErasing program area...\n100% 162.0 KiB |######################################| Elapsed Time: 0:00:01\nFlashing firmware.hex...\n100% 98.8 KiB |#######################################| Elapsed Time: 0:00:06\nSelf verify OK\n```\n\n### Library\n\nWhen using mcbootflash as a library, typical workflow looks something like this:\n\n``` py\nimport mcbootflash as bf\nimport serial\n\n\n# Connect to a device in bootloader mode.\nconnection = serial.Serial(port=<PORT>, baudrate=<BAUDRATE>, timeout=<TIMEOUT>)\n# Query its attributes.\nbootattrs = bf.get_boot_attrs(connection)\n# Load the firmware image and split it into chunks.\ntotal_bytes, chunks = bf.chunked(hexfile=<HEXFILE_PATH_STRING>, bootattrs)\n# Erase the device's program memory area.\nbf.erase_flash(connection, bootattrs.memory_range, bootattrs.erase_size)\n\n# Write the firmware chunks to the bootloader in a loop.\nfor chunk in chunks:\n bf.write_flash(connection, chunk)\n\n # Optionally, check that the write is OK by checksumming.\n bf.checksum(connection, chunk)\n\n # At this point, you may want to give an indication of the flashing progress,\n # like updating a progress bar.\n\n# Verify that the new application is detected.\nbf.self_verify(connection)\n```\n\nSee also the [API Reference](https://bessman.github.io/mcbootflash/api/).\n",
"bugtrack_url": null,
"license": null,
"summary": "Flash firmware to devices running Microchip's 16-bit bootloader.",
"version": "10.1.0",
"project_urls": {
"Home": "https://bessman.github.io/mcbootflash/"
},
"split_keywords": [
"firmware",
" flashing",
" bootloader",
" serial",
" uart",
" microchip",
" pic24",
" dspic33",
" 16-bit"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "488ca88274f31bbc8dc1a2bccacfc154bc29d2c2628fec2382dab232122f5dc4",
"md5": "a2c75857099c5bf1c2aae415788cf083",
"sha256": "768648cd9712b5042d7d7864f2339e6ed10c6a4eb8063b1d74dde57c82993eeb"
},
"downloads": -1,
"filename": "mcbootflash-10.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a2c75857099c5bf1c2aae415788cf083",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17244,
"upload_time": "2025-01-16T12:39:27",
"upload_time_iso_8601": "2025-01-16T12:39:27.236352Z",
"url": "https://files.pythonhosted.org/packages/48/8c/a88274f31bbc8dc1a2bccacfc154bc29d2c2628fec2382dab232122f5dc4/mcbootflash-10.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9dd11e90584fae25c20c79bdf8546f4fbce206d8b854b157fb5ffe941094cf58",
"md5": "4a5c313ba8a6155797e9a091134fbf2e",
"sha256": "1d8f381cf34e94b8d78d36c901cb79616d8a48b19b3ea5bfce51f75603b106a5"
},
"downloads": -1,
"filename": "mcbootflash-10.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4a5c313ba8a6155797e9a091134fbf2e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 44252,
"upload_time": "2025-01-16T12:39:30",
"upload_time_iso_8601": "2025-01-16T12:39:30.147723Z",
"url": "https://files.pythonhosted.org/packages/9d/d1/1e90584fae25c20c79bdf8546f4fbce206d8b854b157fb5ffe941094cf58/mcbootflash-10.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-16 12:39:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mcbootflash"
}
JSON