Package: mboot
pyMBootpyMBoot is an Open Source python based library for configuring and upgrading the firmware in NXP Microcontrolers via
embeddedMCUBOOT(MCU Bootloader). Detailed description ofMCUBOOT / KBOOTkey features and functionality is locatedhere.This project is still in developing phase. Please, test it and report founded issues.DependenciesPython >3.6- The interpreter for Python programing languageClick- Python package for creating beautiful command line interface.bincopy- Python package for parsing S-Record, Intel HEX and TI-TXT files.easy_enum- User friendly implementation of documented Enum type for Python language.PyUSB- Python package to access USB devices in Linux OS.PyWinUSB- Python package that simplifies USB-HID communications on Windows OS.pyserial- Python package for communication over Serial port in Linux and Windows OS.Installation$pipinstallmbootTo install the latest version from master branch execute in shell following command:$pipinstall-Uhttps://github.com/molejar/pyMBoot/archive/master.zipIn case of development, install it from cloned sources:$gitclonehttps://github.com/molejar/pyMBoot.git$cdpyMBoot$pipinstall-U-e.NOTE:You may run into a permissions issues running these commands. Here are a few options how to fix it:Run withsudoto install pyMBoot and dependencies globallySpecify the--useroption to install locally into your home directory (export "~/.local/bin" into PATH variable if haven't).Run the command in avirtualenvlocal to a specific project working set.For runningmbootmodule or CLI without root privileges in Linux OS copy following udev rules90-imx-sdp.rulesinto/etc/udev/rules.ddirectory and reload it with command:sudo udevadm control --reload-rules.UsageThe API ofmbootmodule is intuitive and fully reflecting the functionality described in reference manual of any
supported device. It's basic usage is presented in following example.importmbootdevices=mboot.scan_usb()ifdevices:mb=mboot.McuBoot(devices[0])mb.open()# read 100 bytes from address 0data=mb.read_memory(0,100)ifdataisNone:print(mb.status_info)mb.close()exit()# other commands ...mb.close()McuBootclass is supportingwithstatement what is eliminating the explicit call ofopenandclosemethods. The
code then looks more cleaner as you can see in following example.frommbootimportscan_usb,McuBootdevices=scan_usb()ifdevices:withMcuBoot(devices[0])asmb:# read 100 bytes from address 0data=mb.read_memory(0,100)ifdataisNone:print(mb.status_info)exit()# other commands ...If you callreset()command insidewithblock, the device is automatically reopened. You can skip this with
explicit argumentreset(reopen=False)By default is command error propagated by return value and must be processed individually for every command. In many
use-cases is code execution interrupted if any command finish with error. Therefore you have the option to enable the
exception also for command error. The code is then much more readable as you can see in flowing example.frommbootimportscan_usb,McuBoot,McuBootErrordevices=scan_usb()ifdevices:try:withMcuBoot(devices[0],True)asmb:# read 100 bytes from address 0data=mb.read_memory(0,100)# other commands ...exceptMcuBootErrorase:print(str(e))mbootmodule is implementing also logging functionality for easy debugging all communication interfaces. To get it
working you need only importloggingmodule and set the logging level (DEBUGorINFO) with following line of code:logging.basicConfig(level=logging.DEBUG)importlogginglogging.basicConfig(level=logging.DEBUG)The example of terminal output with enabled logging functionality:INFO:MBOOT:Connect: USB COMPOSITE DEVICE (0x15A2, 0x0073)
DEBUG:MBOOT:USB:Open Interface
INFO:MBOOT:CMD: ReadMemory(address=0x00000000, length=100, mem_id=0)
DEBUG:MBOOT:TX-PACKET: Tag=ReadMemory, Flags=0x00, p0=0x00000000, p1=0x00000064, p2=0x00000000
DEBUG:MBOOT:USB:OUT[64]: 01 00 20 00 03 00 00 03 00 00 00 00 64 00 00 00 00 00 00 00 00 00 00 00 00 ...
DEBUG:MBOOT:USB:IN [36]: 03 00 0C 00 A3 01 00 02 00 00 00 00 64 00 00 00 00 00 00 00 00 00 00 00 00 ...
INFO:MBOOT:RX-PACKET: Tag=ReadMemoryResponse, Status=Success, Length=100
DEBUG:MBOOT:USB:IN [36]: 04 00 20 00 00 60 00 20 C1 00 00 00 0D 85 00 00 09 01 00 00 00 00 00 00 00 ...
DEBUG:MBOOT:USB:IN [36]: 04 00 20 00 00 00 00 00 00 00 00 00 00 00 00 00 09 01 00 00 00 00 00 00 00 ...
DEBUG:MBOOT:USB:IN [36]: 04 00 20 00 09 01 00 00 09 01 00 00 09 01 00 00 09 01 00 00 09 01 00 00 09 ...
DEBUG:MBOOT:USB:IN [36]: 04 00 04 00 09 01 00 00 09 01 00 00 09 01 00 00 09 01 00 00 09 01 00 00 09 ...
DEBUG:MBOOT:USB:IN [36]: 03 00 0C 00 A0 00 00 02 00 00 00 00 03 00 00 00 09 01 00 00 09 01 00 00 09 ...
DEBUG:MBOOT:RX-PACKET: Tag=GenericResponse, Status=Success, Cmd=ReadMemory
INFO:MBOOT:CMD: Successfully Received 100 from 100 Bytes
DEBUG:MBOOT:USB:Close Interface[ mboot ] ToolThembootmodule is distributed with command-line utility, which demonstrate the complete functionality of this library
and can be used as replacement ofblhostool. If you writembootinto shell and click enter, then you get the description
of its usage. For getting the help of individual commands just usemboot <command name> -?.$mboot--helpUsage:mboot[OPTIONS]COMMAND[ARGS]...NXPMCUBootloaderCommandLineInterface,version:0.3.0NOTE:Developmentversion,becarefullywithitusage!Options:-t,--targetTEXTSelecttargetMKL27,LPC55,...[optional]-d,--debugINTEGERRANGEDebuglevel:0-off,1-info,2-debug-v,--versionShowtheversionandexit.-?,--helpShowthismessageandexit.Commands:callCallcodefromspecifiedaddressefuseRead/WriteeFusefromMCUeraseEraseMCUinternalorexternalmemoryexecuteExecutecodefromspecifiedaddressfillFillMCUmemorywithspecifiedpatterninfoGetMCUinfo(mbootproperties)keyblobGeneratetheBlobforgivenDEKKeykp-enrollKeyprovisioning:Enrollkp-gen-keyKeyprovisioning:GenerateIntrinsicKeykp-read-kstoreKeyprovisioning:Readthekeyfromkeystoreareakp-read-nvmKeyprovisioning:Readthekeyfromnonvolatilememorykp-user-keyKeyprovisioning:Sendtheuserkeytoabootloaderkp-write-kstoreKeyprovisioning:Writethekeyintokeystoreareakp-write-nvmKeyprovisioning:WritethekeyintononvolatilememorymconfConfigureexternalmemorymlistGetlistofavailablememoriesotpRead/WriteinternalOTPsegmentreadReaddatafromMCUinternalorexternalmemoryresetResetMCUresourceFlashreadresourcesbfileReceiveSBfileunlockUnlockMCUupdateCopybackupappfromaddresstomainappregionwriteWritedataintoMCUinternalorexternalmemoryIf USB device is not in known devices list, then use-t or --targetargument and directly specify the device VID:PID. Example:-t 0x15A2:0x0073$ mboot infoRead bootloader properties from connected MCU.$mbootinfoDEVICE:KinetisBootloader(0x15A2,0x0073)CurrentVersion:K1.0.0AvailablePeripherals:-UART-I2C-Slave-SPI-Slave-USB-HIDFlashStartAddress:0x00000000FlashSize:256.0kiBFlashSectorSize:1.0kiBFlashBlockCount:2AvailableCommands:-FlashEraseAll-FlashEraseRegion-ReadMemory-FillMemory-FlashSecurityDisable-ReceiveSBFile-Call-Reset-SetPropertyVerifyWrites:ONMaxPacketSize:32BReservedRegions:-0x1FFFF800-0x20000687,3.6kiBValidateRegions:ONRamStartAddress:0x1FFFE000RamSize:32.0kiBSystemDeviceIdent:0x23160D82FlashSecurityState:Unlocked$ mboot mlistGet list of available memories (internal and external)$mbootinfoDEVICE:KinetisBootloader(0x15A2,0x0073)InternalFlash:0)0x00000000-0x00040000,Size:256.0kiB,SectorSize:1.0kiBInternalRam:0)0x1FFFE000-0x20006000,Size:32.0kiB$ mboot read [OPTIONS] ADDRESS [LENGTH]Read data from MCU memory and store it into file as binary (.bin), intel-hex (.hex,.ihex) or s-record (.srec, *.s19)
format. If output file is not specified, the data are dumped into stdout in readable format.LENGTH argument is optional and as default will be used the size to end of memoryoptions:-c, --compress- Compress dump output. (default: False)-f, --file-  Output file name with extension: *.bin, *.hex, *.ihex, *.srec or *.s19-?, --help- Show help message and exit.$mbootread0200ReadingfromMCUmemory,pleasewait!ADDRESS|000102030405060708090A0B0C0D0E0F|0123456789ABCDEF-----------------------------------------------------------------------------00000000|00600020C1000000D908000009010000|.`.............00000010|00000000000000000000000000000000|................00000020|00000000000000000000000009010000|................00000030|00000000000000000901000009010000|................00000040|09010000090100000901000009010000|................00000050|09010000090100000901000009010000|................00000060|09010000090100000901000009010000|................00000070|09010000090100000901000009010000|................00000080|09010000090100000901000009010000|................00000090|09010000090100000901000009010000|................000000A0|09010000090100000901000009010000|................000000B0|09010000090100000901000009010000|................000000C0|0A490B4A0B4B9B1A|.I.J.K..-----------------------------------------------------------------------------$ mboot write [OPTIONS] FILEWrite data from attached FILE into MCU memory.options:-a, --address- Start Address. (default: 0)-o, --offset- Offset of input data. (default: 0)-?, --help- Show help message and exit.$mbootwriteblink.srecWroteSuccessfully.$ mboot erase [OPTIONS]Erase MCU memory from specified address and length or complete chip.options:-m, --mass- Erase complete MCU memory.-a, --address- Start Address.-l, --length- Count of bytes aligned to flash block size.-?, --help- Show help message and exit.$mbooterase-mChipErasedSuccessfully.$ mboot unlock [OPTIONS]Unlock MCU memory.options:-k, --key- Use backdoor key as ASCII = S:123...8 or HEX = X:010203...08-?, --help- Show help message and exit.$mbootunlockChipUnlockedSuccessfully.$ mboot fill [OPTIONS] ADDRESS LENGTHFill MCU memory with specified patternoptions:-p, --pattern- Pattern format (default: 0xFFFFFFFF).-?, --help- Show help message and exit.$mbootfill-p0x111111110x1FFFE00010FilledSuccessfully.$ mboot resetMCU SW reset$mbootresetTODOImplement support for UART interface