THIS MODULE ONLY WORKS WITH PYTHON 2.7 or 3.3+.
A utility for flashing the BBC micro:bit with Python scripts and the MicroPython runtime. You pronounce the name of this utility “micro-flash”. ;-)
It provides two services:
Several essential operations are implemented:
To install simply type:
…and the package will download from PyPI. If you wish to upgrade to the latest version, use the following command:
$ pip install --no-cache --upgrade uflash
NB: You must use a USB data cable to connect the micro:bit to your computer (some cables are power only). You’re in good shape if, when plugged in, the micro:bit appears as a USB storage device on your file system.
Linux users: For uflash to work you must ensure the micro:bit is mounted as a USB storage device. Usually this is done automatically. If not you’ve probably configured automounting to be off. If that’s the case, we assume you have the technical knowledge to mount the device yourself or to install the required kernel modules if they’re missing. Default installs of popular Linux distros “should just work” (tm) out of the box given a default install.
Command Usage¶To read help simply type:
or:
To discover the version information type:
If you type the command on its own then uflash will attempt to find a connected BBC micro:bit and flash an unmodified default version of the MicroPython runtime onto it:
$ uflash Flashing Python to: /media/ntoll/MICROBIT/micropython.hex
To flash a version of the MicroPython runtime with a specified script embedded within it (so that script is run when the BBC micro:bit boots up) then pass the path to the Python script in as the first argument to the command:
$ uflash my_script.py Flashing Python to: /media/ntoll/MICROBIT/micropython.hex
You can let uflash watch for changes of your script. It will be flashed automatically every time you save it:
or:
$ uflash --watch my_script.py
At this point uflash will try to automatically detect the path to the device. However, if you have several devices plugged in and/or know what the path on the filesystem to the BBC micro:bit already is, you can specify this as a second argument to the command:
$ uflash myscript.py /media/ntoll/MICROBIT Flashing Python to: /media/ntoll/MICROBIT/micropython.hex
You can even flash multiple devices at once:
$ uflash myscript.py /media/ntoll/MICROBIT /media/ntoll/MICROBIT1 Flashing Python to: /media/ntoll/MICROBIT/micropython.hex Flashing Python to: /media/ntoll/MICROBIT1/micropython.hex
To extract a Python script from a hex file use the “-e” flag like this:
$ uflash -e something.hex myscript.py
This will save the Python script recovered from “something.hex” into the file “myscript.py”. If you don’t supply a target the recovered script will emit to stdout.
If you’re developing MicroPython and have a custom runtime hex file you can specify that uflash use it instead of the built-in version of MicroPython in the following way:
or:
$ uflash --runtime=firmware.hexDevelopment¶
The source code is hosted in GitHub. Please feel free to fork the repository. Assuming you have Git installed you can download the code from the canonical repository with the following command:
$ git clone https://github.com/ntoll/uflash.git
Ensure you have the correct dependencies for development installed by creating a virtualenv and running:
$ pip install -r requirements.txt
To locally install your development version of the module into a virtualenv, run the following command:
$ python setup.py develop
There is a Makefile that helps with most of the common workflows associated with development. Typing make on its own will list the options thus:
$ make There is no default Makefile target right now. Try: make clean - reset the project and remove auto-generated assets. make pyflakes - run the PyFlakes code checker. make pep8 - run the PEP8 style checker. make test - run the test suite. make coverage - view a report on test coverage. make check - run all the checkers and tests. make package - create a deployable package for the project. make publish - publish the project to PyPI. make docs - run sphinx to create project documentation.Contributing to uFlash¶
Hey! Many thanks for wanting to improve uFlash.
Contributions are welcome without prejudice from anyone irrespective of age, gender, religion, race or sexuality. If you’re thinking, “but they don’t mean me”, then we especially mean YOU. Good quality code and engagement with respect, humour and intelligence wins every time.
We expect contributors to follow the Python Software Foundation’s Code of Conduct: https://www.python.org/psf/codeofconduct/
Feedback may be given for contributions and, where necessary, changes will be politely requested and discussed with the originating author. Respectful yet robust argument is most welcome.
Finally, contributions are subject to the following caveat: the contribution was created by the contributor who, by submitting the contribution, is confirming that they have the authority to submit the contribution and place it under the license as defined in the LICENSE file found within this repository.
Checklist¶This module contains functions for turning a Python script into a .hex file and flashing it onto a BBC micro:bit.
Copyright (c) 2015-2018 Nicholas H.Tollervey and others.
See the LICENSE file for more information, or visit:
https://opensource.org/licenses/MIT
uflash.MICROPYTHON_VERSION = '1.0.1'¶
The version number reported by the bundled MicroPython in os.uname().
uflash.embed_hex(runtime_hex, python_hex=None)[source]¶
Given a string representing the MicroPython runtime hex, will embed a string representing a hex encoded Python script into it.
Returns a string representation of the resulting combination.
Will raise a ValueError if the runtime_hex is missing.
If the python_hex is missing, it will return the unmodified runtime_hex.
Given a path_to_hex file this function will attempt to extract the embedded script from it and save it either to output_path or stdout
Given a hex file containing the MicroPython runtime and an embedded Python script, will extract the original Python script.
Returns a string containing the original embedded script.
uflash.find_microbit()[source]¶
Returns a path on the filesystem that represents the plugged in BBC micro:bit that is to be flashed. If no micro:bit is found, it returns None.
Works on Linux, OSX and Windows. Will raise a NotImplementedError exception if run on any other operating system.
uflash.flash(path_to_python=None, paths_to_microbits=None, path_to_runtime=None, python_script=None, minify=False)[source]¶
Given a path to or source of a Python file will attempt to create a hex file and then flash it onto the referenced BBC micro:bit.
If the path_to_python & python_script are unspecified it will simply flash the unmodified MicroPython runtime onto the device.
If used, the python_script argument should be a bytes object representing a UTF-8 encoded string. For example:
script = "from microbit import *\ndisplay.scroll('Hello, World!')"
uflash.flash(python_script=script.encode('utf-8'))
If paths_to_microbits is unspecified it will attempt to find the device’s path on the filesystem automatically.
If the path_to_runtime is unspecified it will use the built in version of the MicroPython runtime. This feature is useful if a custom build of MicroPython is available.
If the automatic discovery fails, then it will raise an IOError.
uflash.get_minifier()[source]¶
Report the minifier will be used when minify=True
uflash.get_version()[source]¶
Returns a string representation of the version information of this project.
uflash.hexlify(script, minify=False)[source]¶
Takes the byte content of a Python script and returns a hex encoded version of it.
Based on the hexlify script in the microbit-micropython repository.
uflash.main(argv=None)[source]¶
Entry point for the command line tool ‘uflash’.
Will print help text if the optional first argument is “help”. Otherwise it will ensure the optional first argument ends in “.py” (the source Python script).
An optional second argument is used to reference the path to the micro:bit device. Any more arguments are ignored.
Exceptions are caught and printed for the user.
uflash.save_hex(hex_file, path)[source]¶
Given a string representation of a hex file, this function copies it to the specified path thus causing the device mounted at that point to be flashed.
If the hex_file is empty it will raise a ValueError.
If the filename at the end of the path does not end in ‘.hex’ it will raise a ValueError.
uflash.strfunc(raw)[source]¶
Compatibility for 2 & 3 str()
uflash.unhexlify(blob)[source]¶
Takes a hexlified script and turns it back into a string of Python code.
uflash.watch_file(path, func, *args, **kwargs)[source]¶
Watch a file for changes by polling its last modification time. Call the provided function with *args and **kwargs upon modification.
Copyright (c) 2015-2018 Nicholas H.Tollervey and others.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4