Code Monkey home page Code Monkey logo

mcbootflash's Introduction

mcbootflash

build Documentation PyPI License

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 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

pip install mcbootflash

Usage

Mcbootflash can be used as both a command-line application and a library.

Command-line

$ mcbootflash --help
usage: mcbootflash [-h] -p PORT -b BAUDRATE [-t TIMEOUT] [-c] [-r] [-v] [-q] [--version] hexfile

Flash firmware over serial connection to a device running Microchip's 16-bit bootloader.

positional arguments:
  hexfile               a HEX file containing application firmware

options:
  -h, --help            show this help message and exit
  -p PORT, --port PORT  serial port connected to the device you want to flash
  -b BAUDRATE, --baudrate BAUDRATE
                        symbol rate of device's serial bus
  -t TIMEOUT, --timeout TIMEOUT
                        try to read data from the bus for this many seconds before giving up
  -c, --checksum        verify flashed data by checksumming after write
  -r, --reset           reset device after flashing is complete
  -v, --verbose         print debug messages
  -q, --quiet           suppress output
  --version             show program's version number and exit

Example

$ mcbootflash --port /dev/ttyUSB0 --baudrate 460800 firmware.hex
Connecting to bootloader...
Erasing program area...
Flashing firmware.hex...
100%  88.7 KiB |########################################| Elapsed Time: 0:00:05
Self verify OK

Library

When using mcbootflash as a library, typical workflow looks something like this:

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.

mcbootflash's People

Contributors

bessman avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

mcbootflash's Issues

struct.error: unpack requires a buffer of 14 bytes

MCU: dsPIC33CH256MP508
mcbootflash version: 6.0.0
Following this issue: #9
Hi bessman, we are still not able to properly flash a dsPIC33CH256MP508 with MCC bootloader. Downloading using mcbootflash generate errors this time. We are able to flash it properly using Microchip Unified Bootloader Host Application v1.19.1 though. Here are the files you previously ask my collegue. Note that "mcbootflash.txt" and "Unified Bootloader Host Application (UBHA).txt" were read using MPLAB and SNAP debugger.

Do not mind asking for further clarification or debug data!

output.txt
app_to_be_programmed.txt
Unified Bootloader Host Application (UBHA).txt
mcbootflash.txt

Flashing failed: BadAddress

MCU: dsPIC33CH512MP508
mcbootflash version: 7.0.3
Following this issue: #13
Hi bessman, we are using a new MCU. this time it is the dsPIC33CH256MP508. Same as the previous one but with 512MB instead of 256MB. We are still not able to properly flash it with MCC bootloader. We are able to flash it properly using Microchip Unified Bootloader Host Application v1.19.1 though. Here are the files you previously ask my colleague. Note that "mcbootflash.txt" and "Unified Bootloader Host Application (UBHA).txt" were read using MPLAB and SNAP debugger.

Do not mind asking for further clarification or debug data!

application.txt
mcbootflash.txt
output.txt
UBHA.txt

Checksum issue

Hello Bessman,

I thought I was having a similar problem to #13. I get the same error message but mine showed up at the very first packet transmission:

output.txt

It turns out that I had forgotten to enable the bootloader checksum command in the MCC. I never caught that before because I think UBHA just ignores it.

Would it be possible and would you be willing to add a command line flag to disable that check?

Many Thanks!

Self-Verify failed on non-aligned hex files

I used this code to understand what is going on UBHA's side and it was very helpful but I found out that some hex files with non-aligned hex addresses cannot be programmed on dsPIC33 devices (like :10D6940073xxxxx). The same thing happend on my onboard programmer which employed Zephyr OS to reproduce UBHA actions. I fixed the issue by putting extra heading 0xFF before the sent data and it worked for me.

Always erase

The CLI tries to determine if an application already exists by doing self_verify, and skips erase if the result is negative. Problem is, a negative self_verify response only indicates that something is wrong with the existing application. It could be that is doesn't exist, but it could also be something else.

Since there is no way to determine if an application exists (short of a full readback, which is too time consuming), it is safer to always erase.

BadAddress while checksumming

Alexander ,

My name is Josep Maria Vernet , currently Iโ€™m working in a dspic project and looking for a tool for get it updated in field...

The bootloader is implemented in my design , and looking for a tool for flash the device I found mcbootflash...

In first , I beg your pardon , Iโ€™m not experienced in python , but yes in C , I need to learn a lot due , that surely I will try to use your code as a Lib.

My first test was call it using the cmd under win10 :

            mcbootflash --port /dev/ttyUSB6 --baudrate 115000 CK256MP206production.hex

And yes , it works , but , the program does not start....

How can I pass the memory addresses to flash , erase.... like in the Unified Bootloader tool ?

Thanks in advance ,

Josep Maria Vernet
Catalonia.


Hello Josep,

The bootloader is implemented in my design , and looking for a tool for flash the device I found mcbootflash...

To what extent does your bootloader differ from what MCC generates?
Mcbootflash probably won't work if you diverge too much from the
default behavior.

And yes , it works , but , the program does not start....

To help you troubleshoot this, I need a few things:

  1. Debug output from mcbootflash. Run mcbootflash --port /dev/ttyUSB6 --baudrate 115000 CK256MP206production.hex --verbose 2>&1 | tee log.txt. This will create a file, 'log.txt', which contains the debug
    info I need
  2. A copy of your application HEX, CK256MP206production.hex.

And, ideally, if you can get it:

  1. Full readbacks of your device's flash memory after flashing with
    3.1 mcbootflash, and
    3.2 UBHA.

This would allow me to compare what mcbootflash does to what UBHA
does, and hopefully figure out what the difference is.

How can I pass the memory addresses to flash , erase.... like in the Unified Bootloader tool ?

On the command line, you cannot. When using mcbootflash as a Python
library, you can control the erase region. However, the addresses to
flash is largely governed by the metadata contained in the HEX file,
as well as in the bootloader itself.

The way it works is, the bootloader tells the flashing application
(whether that is UBHA or mcbootflash) the address range to which it is
possible to flash application data (the 'program memory range'). The
HEX file contains memory addresses and the data which should be
written to those addresses. Using these pieces of information,
mcbootflash writes all data with addresses within the program memory
range. As such, currently the only way to control the addresses to
flash is to modify the HEX file.

When you flash your application using UBHA, could you describe the
steps you take to specify the memory addresses to flash?

Regards,
Alexander Bessman


Alexander ,

Happy for the fast reply , thanks
I'm using the MCC standard bootloader configuration , you can se the image attached , also the hex file is attached , it only contains the application , not the bootloader code.

I know that I MUST learn a lot of this and Python... , But a llithe help is welcome !

Thanks

Josep Maria Vernet
[Attachments omitted]


Here is the log attached ,
Thanks ,

Josep Maria Vernet.
teelog.txt


Thank you for the log. This is a bug in mcbootflash, I will release a
fix as soon as I can, probably tonight or tomorrow.

Bad Address again

Regression: #21 is back.

Cause: I forgot to add the optional padding parameter to bincopy.BinFile.segments.chunks when upgrading to bincopy 20.0.0. Therefore the first chunk may be misaligned and the final chunk may have the wrong size.

Solution: Add padding=b"\x00\x00" to chunks call.

Feature request: Remove dependency to 'progressbar' when running quiet

Hi,

I'm using this application for a Yocto Linux build, performing updates of a PIC24 through SWUpdate. While I'm very happy with the application, i found it a bit messy to add 'progressbar' and its dependencies that are not present in Yocto. So i wrote a patch that removes all references to 'progressbar'. A neat feature would be to skip the import and progressbar functions if running quiet. (Not sure if this is good practice for Python, mostly work in C...)

Thanks again for this excellent piece of code ๐Ÿ˜„

Where is the upper end of the program memory range?

Split from #13.

Problem description

I am currently using version 7.0.2 and I still have an error. The problemed seems to come when verifying the integrity of the written app. output.txt mcbootflash.txt

Analysis

Looking at the provided readbacks, the problem looks related to those pernicious four final bytes right on the edge of the program memory range. Those are the only four which differ:

program_memory_range

I had interpreted the program memory range (PMR) reported by the bootloader as a half-open range, like Python's range. It seems it's actually closed on both ends; UBHA has written 0x5000 to address 0x2B7FE, which is the upper end of the PMR.

Strangely, UBHA seems to have written 0x0000 to address 0x2B7FF, which should be strictly outside the PMR. I would have expected an attempt to write there to fail with BAD_ADDRESS. Could it have something to do with the 24-bit instruction width? Should the odd address after the reported upper memory bound be considered the actual end of the PMR?

Next step

The upper bound of the PMR reported by the bootloader should be considered valid for writing.

Need to investigate if it is necessary to also attempt to write to one additional address beyond that.

Flash erase may time out

dsPIC33CK512MP608

  1. create sample bootloader and host application
  2. burn bootloader
  3. using Microchip Unified Bootloader Host Application download the firmware
  4. reset the MCU and download again: all works as expected

By the way, the first time it does not erase the flash since there no valid image is found.
Instead:

  1. create sample bootloader and host application
  2. burn bootloader
  3. using mcbootflash download the firmware
  4. reset the MCU and download again:
Connecting to bootloader...
Connected
Erasing flash...
Traceback (most recent call last):
  File "/home/mark/.local/lib/python3.10/site-packages/mcbootflash/protocol.py", line 87, in from_bytes
    return cls(*struct.unpack(cls.FORMAT, data))
struct.error: unpack requires a buffer of 12 bytes

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/mark/.local/lib/python3.10/site-packages/mcbootflash/flashing.py", line 115, in flash
    boot.flash(hexfile=parsed_args.file, quiet=parsed_args.quiet)
  File "/home/mark/.local/lib/python3.10/site-packages/mcbootflash/connection.py", line 106, in flash
    self.erase_flash(self._memory_range)
  File "/home/mark/.local/lib/python3.10/site-packages/mcbootflash/connection.py", line 286, in erase_flash
    self._erase_flash(start, end)
  File "/home/mark/.local/lib/python3.10/site-packages/mcbootflash/connection.py", line 300, in _erase_flash
    self._send_and_receive(
  File "/home/mark/.local/lib/python3.10/site-packages/mcbootflash/connection.py", line 187, in _send_and_receive
    response = _RESPONSE_TYPE_MAP[command.command].from_serial(self.interface)
  File "/home/mark/.local/lib/python3.10/site-packages/mcbootflash/protocol.py", line 96, in from_serial
    return cls.from_bytes(interface.read(cls.get_size()))
  File "/home/mark/.local/lib/python3.10/site-packages/mcbootflash/protocol.py", line 89, in from_bytes
    raise struct.error(
struct.error: <class 'mcbootflash.protocol.Response'> expected 12 bytes, got 0.

This is reproducible on my system every time.

Missing a small portion of the non-contiguous .hex file on dsPIC33CH256MP508

Using mcbootflash version 5.1.1 I am not able to properly flash a dsPIC33CH256MP508 with MCC bootloader. Downloading using mcbootflash doesn't generate any error but the program is not functionnal.
I am able to flash it properly using Microchip Unified Bootloader Host Application v1.19.1. The program works.

Using MPLAB and SNAP debugger, I was able to read back the downloaded .hex file with both programs but mcbootflash missed a section at the end of the program. I suspect this missing section explains why the program doesn't work with mcbootflash. The hex file I want to download is not contiguous. I have attached both the Java application downloaded hex and the mcbootflash downloaded hex so you can see the difference if you diff those two files.
I suspect this a is problem with the initial hex file parsing of mcbootflash but I may be wrong too...

If you need further clarification or debug data I would be happy to provide it!
Thank you and good luck.
python_mcbootflash_read.txt
java_unified_bootloader_read.txt

C++ version

Hi,

First of all, thank you for creating this library. But I needed a solution to flash my PIC24s from my Linux embedded system without relying on Python.

Inspired by your library, I developed (or more accurately, copy-pasted-chatgpted) a C++ version that replicates its functionality. This is still an experimental version, and I've made it available here. The structure and function names mirror those of your library, with some necessary adaptations due to language differences (such as the absence of generators in C++).

Currently, it doesn't include a flashing utility like yours, but focuses on converting hex files into "chunks" and achieving the same results as your implementation.

The code isn't perfect yet, but it might be useful to someone in its current state.

If anyone has suggestions for improvements or would like to contribute, feel free to reach out or submit a pull request. Any feedback is welcome!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.