carlosperate/ubittool

Utility to extract the contents of flash from a micro:bit, including MicroPython user code.

uBitTool

uBitTool is a command line and GUI application to interface with the micro:bit.

It can:

• Read the micro:bit flash contents
• Extract user Python code from the micro:bit flash
• Flash the micro:bit
• Compare the contents of the micro:bit flash against a local hex file

Docs

The documentation is online at https://carlosperate.github.io/ubittool/, and its source can be found in docs directory.

Basic Introduction

The easiest way to use uBitTool is via the application GUI.

• Download one of the latest GUI executables for macOS or Windows from the GitHub Releases Page.
• Plug-in your micro:bit to the computer via USB
• Open the GUI executable file
• On the application menu click "nrf > Read Full Flash contents (Intel Hex)".
• A full image of the micro:bit flash should now be displayed in the GUI :)

For more information and instructions for other platforms please visit the Documentation.

ubittool's Issues

Failure to read code from v1.x Microbit

Seen this problem when trying to extract code from a microbit where we have lost the source.

 ~/ Downloads/ubittool-0.6.0-mac-cli read-code
Executing: Extract the MicroPython code to a file or print it.

MicroPython code will be output to console.
Reading the micro:bit flash contents...
Traceback (most recent call last):
File "ubittool/cmds.py", line 164, in read_python_code
File "uflash.py", line 200, in extract_script
File "uflash.py", line 128, in unhexlify
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x8a in position 1: invalid start byte

---

Error: Could not decode the MicroPython code from flash
 ~/

I have attached the output of the read-flash command for reference.

DETAILS.TXT
read-flash-output.txt.gz

Windows executable file is larger than expected

The macOS executable increased from 11 MBs to 15 MBs, but the Windows increased from 13 MBs to 29 MBs.

I'll need to build on Windows onto a folder (instead of a single file executable) to figure out what's taking so much space.

Fully move from pipenv to poetry

Once we are confident poetry meets all the project needs.

GUI crashes on macOS

When a second operation/command is executed.
The first one seems to run correctly, but running a second one seems to crash the app.

To reproduce:

• python -m ubitflashtool gui
• Click nrf/Read UICR Customer
• Wait for results
• Click nrf/Read UICR Customer
• App crashes

Terminal output:

Fatal Python error: PyEval_RestoreThread: NULL tstate
[1]    29862 abort      python -m ubitflashtool gui

Running the built cli apps raise an exception

A missing package, maybe it needs and updated PyInstaller or hook.

Windows:

> ubittool-cli.exe --help
Traceback (most recent call last):
  File "C:\Users\appveyor\.virtualenvs\ubitextract-FgtoUL4O\Lib\site-packages\PyInstaller\loader\rthooks\pyi_rth_pkgres.py", line 13, in <module>
    import pkg_resources as res
  File "c:\users\appveyor\.virtualenvs\ubitextract-fgtoul4o\lib\site-packages\PyInstaller\loader\pyimod03_importers.py", line 623, in exec_module
    exec(bytecode, module.__dict__)
  File "site-packages\pkg_resources\__init__.py", line 86, in <module>
ModuleNotFoundError: No module named 'pkg_resources.py2_warn'
[1916] Failed to execute script pyi_rth_pkgres

macOS:

$ ./ubittool-cli --help
Traceback (most recent call last):
  File "PyInstaller/loader/rthooks/pyi_rth_pkgres.py", line 13, in <module>
  File "/Users/travis/.local/share/virtualenvs/ubittool-PRs-Fujz/lib/python3.6/site-packages/PyInstaller/loader/pyimod03_importers.py", line 623, in exec_module
  File "pkg_resources/__init__.py", line 86, in <module>
ModuleNotFoundError: No module named 'pkg_resources.py2_warn'
[73645] Failed to execute script pyi_rth_pkgres

"No available boards are connected" in Ubuntu

When testing in 17.04, very likely related to pyocd/pyOCD#267.

Docs: Add Windows installation instructions

https://www.embeddedlog.com/ubittool/installation.html

With screenshots showing how to run an unsigned executable.

Executable CLI does not include tkinter

So we should either not show the command or show an error message that explains the situation.

$ ./ubittool-cli gui
Traceback (most recent call last):
  File "ubittool/cli.py", line 158, in <module>
  File "ubittool/cli.py", line 154, in main
  File "click/core.py", line 829, in __call__
  File "click/core.py", line 782, in main
  File "click/core.py", line 1259, in invoke
  File "click/core.py", line 1066, in invoke
  File "click/core.py", line 610, in invoke
  File "ubittool/cli.py", line 147, in gui
  File "/Users/travis/.local/share/virtualenvs/ubittool-PRs-Fujz/lib/python3.6/site-packages/PyInstaller/loader/pyimod03_importers.py", line 623, in exec_module
  File "ubittool/gui.py", line 7, in <module>
ModuleNotFoundError: No module named 'tkinter'
[73676] Failed to execute script cli

Windows executable sometimes times out

I saw this when using a Windows VM, but after a couple of attempts with older CI builds (to see if it was introduced in a specific commit) it stopped timing out with any version.

I will need to try to replicate this one again. v0.7.0 and earlier never showed this issue.

Microbit HEX file is not importing to the MakeCode Editor

Wiped my chromebook a while back, including all my Microbit hexes, which was not very smart.
Anyways, tried to recover one hex I had on my microbit, but the hex can't be accessed via the Makecode editor.
iogameplayer github issue.txt
Github does not support .hex files, so just rename it to [something].hex. Thanks for reading :D!

Error installing Pyyaml==5.4.1

Problem

~$ pipx install ubittool

pip seemed to fail to build package:
    pyyaml<6.0,>=5.1

Some possibly relevant errors from pip install:
    error: subprocess-exited-with-error
    AttributeError: cython_sources

Error installing ubittool.

And from the install log:

Collecting pyyaml<6.0,>=5.1 (from pyocd==0.19.0->ubittool)
  Downloading PyYAML-5.4.1.tar.gz (175 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 175.1/175.1 kB 715.9 kB/s eta 0:00:00
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: started
  Getting requirements to build wheel: finished with status 'error'

PIP STDERR
----------
  error: subprocess-exited-with-error

Looks like there's a problem in yaml/pyyaml#724

Workaround

A workaround is to specify an earlier pyyaml version:

$ echo 'pyyaml!=6.0.0,!=5.4.0,!=5.4.1' > pyyaml.txt
$ pipx install ubittool --pip-args '-c pyyaml.txt'

Error in the Compare Full Flash Contents GUI output box (although it works)

On Windows:

...
FPU present: FPv4-SP
4 hardware watchpoints
6 hardware breakpoints, 4 literal comparators
Exception in thread Thread-10:
Traceback (most recent call last):
  File "threading.py", line 932, in _bootstrap_inner
  File "threading.py", line 1254, in run
  File "ubittool\cmds.py", line 188, in <lambda>
PermissionError: [WinError 32] The process cannot access the file because it is being used by another process: 'C:\\Users\\[removed]\\AppData\\Local\\Temp\\tmp18wfnz_b.html'

So it can't forcefully remove the temp file because it is being used by a different process (the browser most likely).

This is not much of a problem as the file was created in a temp folder.

Extract flash+UICR for MicroPython file retrieval

Right now uBitTool can either read the flash contents or the UICR, but not a hex file containing both.
If a hex file (with MicroPython files) without the UICR is dropped into the Python Editor it cannot read the filesystem, so providing the functionality will be useful to retrieve that data.