Setup Guide for build environment on Debian 8 (Jessie)

[c-mart]

I had to jump around the docs and ask others for help, and from this experience, I produced the following guide. The existing "Debian and Ubuntu" section of the installation guide specifies adding new APT repositories but I found this wasn't necessary for Debian, everything is in stable/main.

I feel there is no problem keeping a set of distro-specific setup guides, as long as someone is willing to maintain each guide, which I'm happy to do for Debian. I would break up the "Debian and Ubuntu" section of the installation docs into a separate section for each distro. (I would also work some of this into flashfirmware.rst and other docs.)

What do others think, would these contributions be welcome?

---

Setup Guide: micro:bit MicroPython build environment on Debian 8 (Jessie)

This will allow you to build your own firmware and play with new features (like the radio module) which aren't in the official firmware yet. You don't need to do this if you only want to run Python code using the official firmware - you can just use Mu or uflash.

APT Packages

All packages should be available in the Jessie/stable main repository. Open /etc/apt/sources.list and ensure that you have entries for the jessie main or stable main APT repository per Debian's instructions.

Acquire root privileges with su, or install sudo and pre-pend sudo and a space to all of the following apt-get commands.

Run apt-get update, then install these packages by running apt-get install.

• binutils-arm-none-eabi
• gcc-arm-none-eabi
• libnewlib-arm-none-eabi
• libnewlib-dev
• libstdc++-arm-none-eabi-newlib
• srecord
• cmake
• ninja-build
• python-virtualenv
• python-dev
• libffi-dev
• libssl-dev
• git

Or, in one line:

apt-get install binutils-arm-none-eabi gcc-arm-none-eabi libnewlib-arm-none-eabi libnewlib-dev libstdc++-arm-none-eabi-newlib srecord cmake ninja-build python-virtualenv python-dev libffi-dev libssl-dev git

Python Environment

Give up your root privileges (either stop using sudo or run exit if you used su). You shouldn't need them for the rest of the setup.

Create a virtualenv and activate it:

virtualenv microbit-venv
source microbit-venv/bin/activate

Install yotta, markupsafe (required by yotta), and uflash inside your virtualenv:

pip install yotta markupsafe uflash

Get Repository

If you want to start with the official bbcmicrobit repo: git clone https://github.com/bbcmicrobit/micropython.git

If you want to try the experimental radio module: git clone https://github.com/dpgeorge/bbcmicrobit-micropython.git

Building firmware

cd into the root of the repository and run yt target bbc-microbit-classic-gcc-nosd. This will prompt you to sign up for an ARM mbed account, and you will need to confirm your email address. After you sign up, run yt target bbc-microbit-classic-gcc-nosd again, log in with your browser when prompted. You may need to run the command a third time after logging in, it should eventually execute with no errors.

Update yotta and run the build:

yt up
yt build

If all goes well, your firmware .hex file will be saved to build/bbc-microbit-classic-gcc-nosd/source/microbit-micropython.hex.

Flashing firmware

Plug in your micro:bit. It should be mounted as a mass storage device.

You can flash your new firmware either using uflash or by copying the .hex file. uflash allows you to flash with a Python script of your choosing, while copying the .hex file will just flash the firmware and the micro:bit will boot to the REPL. Whether you use uflash or copy a .hex file, the firmware will flash to the microbit, yellow LED will blink for a few seconds, and then the micro:bit will boot.

Using uflash

General usage:

uflash -r [path to firmware] [path to Python file] [path to micro:bit mass storage volume]

Example:

uflash -r build/bbc-microbit-classic-gcc-nosd/source/microbit-micropython.hex examples/space_shoot_multiplayer.py /home/yourname/media/MICROBIT

By copying a .hex file

Simply copy build/bbc-microbit-classic-gcc-nosd/source/microbit-micropython.hex from the repository to the root directory of the MICROBIT volume (probably at /media/yourname/MICROBIT).

[c-mart]

Just tested this guide by setting up another PC from a clean Debian installation. Made several changes, and I am now confident that this guide works for Debian stable.

[ntoll]

I'll check all this with latest 16.04 LTS. I don't mind supporting Ubuntu either. I'll work out where's best to put this sort of documentation in our current docs sub-directory. There probably needs to be pages for Windows, OSX and Redhat/Fedora too.

[bfayers]

After I flash my built firmware, is there anyway to have it stick, without having to use makecombinedhex.py or uflash? otherwise it just acts like a regular program where when flashing something new it will overwrite it and go back to stock firmware

[ntoll]

You can use uflash to use your custom firmware. See the bit about the -r / --runtime option here: https://uflash.readthedocs.io/en/latest/ e.g.

uflash -r custom_runtime.hex my_python_script.py

[bfayers]

I have done this, i just wanted a slightly easier way of getting ode on without uflash etc, I found how anyway simply just flashed my firmware then used ufs put to put main.py and it keeps the python version + code

[nickbailey]

I followed the instructions you gave and everything runs fine right up until the yt build. The C++ compilations fail with

In file included from /home/nick/Microbit/micropython/yotta_modules/mbed-classic/api/BusIn.h:19:0,
                 from /home/nick/Microbit/micropython/yotta_modules/mbed-classic/common/BusIn.cpp:16:
/home/nick/Microbit/micropython/yotta_modules/mbed-classic/api/platform.h:25:19: fatal error: cstddef: No such file or directory
compilation terminated.

Looking at the compiler search paths:

nick@ariel:~/Microbit/micropython$ /usr/bin/arm-none-eabi-g++ -E -x c++ - -v < /dev/null
...
#include <...> search starts here:
 /usr/lib/gcc/arm-none-eabi/5.4.1/include
 /usr/lib/gcc/arm-none-eabi/5.4.1/include-fixed
 /usr/lib/gcc/arm-none-eabi/5.4.1/../../../arm-none-eabi/include
End of search list.

So how did I end up with different compiler and library versions with newly installed packages? Debian issue?

I can make the code compile under the more recent compiler with by saying export CPATH=:/usr/include/newlib/c++/4.9.3/arm-none-eabi and export CPLUS_INCLUDE_PATH=:/usr/include/newlib/c++/4.9.3 but then linkage happens against code compiled with a different sizeof(w_char) resulting in a load of errors of the form

/usr/lib/gcc/arm-none-eabi/5.4.1/../../../arm-none-eabi/bin/ld: warning: /usr/lib/gcc/arm-none-eabi/5.4.1/../../../arm-none-eabi/lib/armv6-m/libc_nano.a(lib_a-nano-msizer.o) uses 2-byte wchar_t yet the output is to use 4-byte wchar_t; use of wchar_t values across objects may fail

There are also a bunch of warnings about non-static data initialisers such as

/home/nick/Microbit/micropython/yotta_modules/microbit-dal/inc/MicroBitLightSensor.h:48:55: warning: non-static data member initializers only available with -std=c++11 or -std=gnu++11
     int results[MICROBIT_LIGHT_SENSOR_CHAN_NUM] = { 0 };

and variable size issues

/home/nick/Microbit/micropython/source/lib/sam/render.c:71:11: warning: comparison is always false due to limited range of data type [-Wtype-limits]
     if (p > RENDER_FRAMES) {

which may or may not be related.

The resulting build does seem to work. But I'm not inspired with confidence.

Is the position just that the old compiler is required? It's a pity, because I'd like to use the boards for teaching at an undergraduate level on the Linux platform with Python, and experience shows that developing materials on anything older than Testing goes out-of-date virtually before it can be deployed. I'd therefore be happy to put in a bit of work to get things working with the testing/sid toolchain.

[kjcole]

The firmware-microbit-micropython Ubuntu package contains /usr/share/firmware-microbit-micropython/firmware.hex but apparently that is not quite right? I will try reaching out to the Ubuntu gang that packages it, but just for a data point here:

Package: firmware-microbit-micropython
Version: 1.0.1-1
Installed-Size: 732
Maintainer: Python Applications Packaging Team <[email protected]>
Architecture: all
Suggests: firmware-microbit-micropython-doc, picocom | screen
Enhances: mu-editor, python3-uflash
Conflicts: firmware-microbit-micropython-dl
Description-en: MicroPython runtime for the BBC micro:bit
 This package provides a binary firmware file for the  BBC micro:bit
 small board computer (SBC), containing the MicroPython runtime.
 .
 It is suggested that a dedicated flashing tool (e.g. uflash) is used to
 upload the firmware and Python scripts to the micro:bit device.
 .
 The uflash utility (package: python3-uflash) uses the MicroPython runtime
 provided in this package as the default firmware to flash to the micro:bit.
 .
 This package contains the MicroPython runtime for the BBC micro:bit
Description-md5: df6e22bc90b84c449f3657f35bb30f52
Homepage: https://github.com/bbcmicrobit/micropython
Section: python
Priority: optional
Filename: pool/main/f/firmware-microbit-micropython/firmware-microbit-micropython_1.0.1-1_all.deb
Size: 216240
MD5sum: 052afefb10bc8310766f7752a4572f9a
SHA256: 0c977bd81e284e966ae00d1d17759d346a0bc304d90eb240792acf6e28faceae