Real time accelerometer display from three BBC Micro:bits

I submitted an article to Circuit Cellar magazine on how I get real time data display from three BBC Micro:bits real time. Please find a video showing this in action below. On the screen to the right of the juggling clown, you can see the accelerometer data. Each BC Micro:bit has a three axis accelerometer in it. For each Micro:bit I get the average from all three axis as a single value. On the screen three are three traces, one for each Micro:bit. As the boards are juggled, the accelerometer values are sent by radio to a receiver Micro:bit connected to the computer. This Micro:bit acts as a go-between for the juggled Micro:bits and the computer. The accelerometer data is plotted real time using a script I wrote in Python, using the pyqtgraph library.

Using udev to remove the need for sudo with the BBC Micro:bit

A comment on this post hinted that there is a way to remove the need to use ‘sudo’ when interacting with the BBC Micro:bit on Linux. So I left a comment asking how to do this, which the author kindly answered:

The way to make sure there is no need for root permissions to access USB device (like connected MicroBit) is by creating a file into `/etc/udev/rules.d/` directory with proper config. For Microbit this could be like this:

SUBSYSTEM=="usb", ATTR{idVendor}=="0d28", ATTR{idProduct}=="0204", MODE="0666"
and then restarting udev system with:
sudo udevadm control --reload-rules

So I created the file /etc/udev/rules.d/microbit.rules with the above code and it works!

I fired up pyocd to enable command line programming of the BBC Micro:bit without needing to use sudo. See this page for more details on programming the BBC Micro:bit from the command line and using pyocd to help with this.

Zombie BBC Micro:bit serial ports created when using pyocd-gdbserver –persist

So I was happily using pyocd-gdbserver to program and enter debugging mode on a BBC Micro:bit attached to one of my laptop’s USB port, as described here. Then I stopped being able to read data through the USB port… Long story short, multiple ‘zombie’ ports were created and my Python script was connecting to a zombie instead of the live one.

setserial -g /dev/ttyACM*

output:

/dev/ttyACM0, UART: unknown, Port: 0x0000, IRQ: 0, Flags: low_latency
/dev/ttyACM1, UART: unknown, Port: 0x0000, IRQ: 0, Flags: low_latency

Sometimes for fun, I would also see a ttyACM2. Why would two ports have the same Port number? The answer is they don’t. They are the same port. Connecting to /dev/ttyACM1 got me nothing. Connecting to /dev/ttyACM0 got me connected to the BBC Micro:bit. I had set the pyocd-gdb utility running using:

sudo ~/.local/bin/pyocd-gdbserver -t nrf51 -bh -r --persist

I think that the –persist flag does the damage. Run the script without this and I think we are good to go. I altered my serial port script to flag up when more than one Micro:bit is found. For good measure, I sort the ports into reverse order and connect to the first one with the PID and VID for the Micro:bit, which will be the lowest numbered ttyACM port. This is a work around when zombies appear.

Please find my Python 3 serial_port.py script for finding and returning a serial port connection to a BBC Micro:bit below.

import logging
import serial
import serial.tools.list_ports as list_ports
from time import sleep

BAUD = 115200
PID_MICROBIT = 516
VID_MICROBIT = 3368
TIMEOUT = 0.1

logging.basicConfig(level=logging.DEBUG, format='%(message)s')


class SerialPort():
    def __init__(self, pid=PID_MICROBIT, vid=VID_MICROBIT, baud=BAUD, timeout=TIMEOUT):
        self.serial_port = self.open_serial_port(pid, vid, baud, timeout)


    def count_same_ports(self, ports, pid, vid):
        ''' Count how many ports with pid and vid are in <ports>. '''
        return len([p for p in ports if p.pid==pid and p.vid==vid])


    def get_serial_data(self, serial_port):
        ''' get serial port data '''
        inWaiting = serial_port.inWaiting()
        read_bytes = serial_port.readline(inWaiting)
        if not read_bytes:
            return
        return read_bytes.decode()


    def get_serial_port(self):
        ''' Return the serial port. '''
        return self.serial_port


    def open_serial_port(self, pid=PID_MICROBIT, vid=VID_MICROBIT, baud=BAUD, timeout=TIMEOUT):
        ''' open a serial connection '''
        print('looking for attached microbit on a serial port')
        # serial = find_comport(pid, vid, baud)
        serial_port = serial.Serial(timeout=timeout)
        serial_port.baudrate = baud
        ports = list(list_ports.comports())
        print('scanning ports')
        num_mb = self.count_same_ports(ports, pid, vid)
        logging.info('{} microbits found'.format(num_mb))
        if num_mb>1:
            logging.info('**** check for false connections ****')
        ports.sort(reverse=True)
        for p in ports:
            print('pid: {} vid: {}'.format(p.pid, p.vid))
            if (p.pid == pid) and (p.vid == vid):
                print('found target device pid: {} vid: {} port: {}'.format(
                    p.pid, p.vid, p.device))
                serial_port.port = str(p.device)
        if not serial:
            print('no serial port found')
            return None
        try:
            serial_port.open()
            serial_port.flush()
            print('opened serial port: {}'.format(serial))
        # except (AttributeError, SerialException) as e:
        except Exception as e:
            print('cannot open serial port: {}'.format(e))
            return None
        # 100ms delay
        sleep(0.1)
        return serial_port


if __name__ == '__main__':
    print('instatiating SerialPort()')
    serial_port = SerialPort()
    print('finished')

Eclipse, yotta, C/C++ and the BBC Micro:bit

With the help of the excellent instructions at the link below I set up Eclipse with yotta to compile C code for the BBC Micro:bit under Linux:
http://flames-of-code.netlify.com/blog/microbit-cpp-3/
I get the debugger window to come up, but have not yet used this feature in anger.
The writer, achary, clearly knows more about Eclipse and embedded programming than I do. I got a little stuck at a couple of stages so created this page to pass on my solutions.

The offline C compiler for the BBC Micro:bit is developed at Lancaster University. Installing the yotta compiler and downloading example files is explained here.

The rest of this article assumes you followed the instructions on this installation guide and have cloned the microbit-samples directory. I assume that you have Eclipse installed, either the C/C++ installation or you have installed the C/C++ development environment.

Installing yotta

Instructions for installing yotta can be found in the yotta documentation here. Note that yotta is designed for Python2.7 only. I used pip to install yotta to my user directory, using the –user flag. Then I started getting errors:

‘module’ object has no attribute ‘X509_up_ref’

I faffed around upgrading my cryptography library as mentioned in the yotta documentation. Long story short, the recently installed ‘yotta’ and ‘yt’ commands in ~/.local/bin/yt and ~/.local/bin/yotta both referred to python 3. I probably did something sometime to cause this. To fix the error I changed ~/.local/bin/yt and ~/.local/bin/yotta from:

#!/usr/bin/python3.6

import yotta
yotta.main()

To:

#!/usr/bin/python2.7

import yotta
yotta.main()

Get yotta to work in debug mode

Using yotta with the –debug-build flag allows for easier debugging. By default, the code is compiled in an optimised mode which makes debugging harder. I need all of the help that I can get, so would like to use this flag. The command to run yotta with the –debug-build flag  is:

yotta build --debug-build

However, this will throw an error and the last line of the build will give the erro:

ninja: build stopped: subcommand failed.

I am not sure what a ninja is doing in my system. If I could see him, I would probably already be dead.

To fix this error, the ‘-fomit-frame’ flag needs adding at two places in the file yotta_targets/mbed-gcc/CMake/Platform/mbedOS-GNU-C.cmake in your microbit-samples directory.

The two changes to mbedOS-GNU-C.cmake are:

line 21 from:
set(CMAKE_C_FLAGS_DEBUG_INIT “-g -gdwarf-3”)
to:
set(CMAKE_C_FLAGS_DEBUG_INIT “-g -gdwarf-3 -fomit-frame-pointer”)
line 28 from:
set(CMAKE_ASM_FLAGS_DEBUG_INIT “-g -gdwarf-3”)
to:
set(CMAKE_ASM_FLAGS_DEBUG_INIT “-g -gdwarf-3 -fomit-frame-pointer”)

Then remove the build directory in the microbit-samples directory and rebuild using:

yotta build --debug-build

If you don’t remove the old build directory directory, then the command will still fail. I know this.

Install pyOCD

We use the pyOCD tool to help debug and program the microbit. Details of this tool are on its github page.

‘pyOCD is an Open Source python 2.7 based library for programming and debugging ARM Cortex-M microcontrollers using CMSIS-DAP. Linux, OSX and Windows are supported.’

Note the ‘python 2.7’ bit. Initially I pip installed it, which defaulted to a python 3 install. The install worked, but when I came to try running pyocd, I got a  bunch of assertion errors. So I read the instructions…

To ensure that pyocd is installed using python2.7, I used:

pip2 install --pre -U --user pyocd

–pre # ‘Include pre-release and development versions. By default, pip only finds stable versions.’ from https://pip.pypa.io/en/stable/reference/pip_install/#install-pre
-U # same as –upgrade ‘Upgrade all specified packages to the newest available version.’
–user # libraries go to the user directory. In linux, this removes the need for sudo to install, which is a security issue.

Plug in your microbit.

Now we fire up a gdbserver using the newly installed pyocd. What is a gdbserver? This wikipedia page explains that ‘gdbserver is a computer program that makes it possible to remotely debug other programs.’

sudo ~/.local/bin/pyocd-gdbserver -t nrf51 -bh -r

-t # target (nrf51 is the chipset used on the microbit).
-bh # replace software breakpoints with hardware breakpoints.
-r # halt the target when reset.

I get this output:

INFO:root:DAP SWD MODE initialised
INFO:root:ROM table #0 @ 0xf0000000 cidr=b105100d pidr=2007c4001
INFO:root:[0]&amp;lt;e00ff000: cidr=b105100d, pidr=4000bb471, class=1&amp;gt;
INFO:root:ROM table #1 @ 0xe00ff000 cidr=b105100d pidr=4000bb471
INFO:root:[0]&amp;lt;e000e000:SCS-M0+ cidr=b105e00d, pidr=4000bb008, class=14&amp;gt;
INFO:root:[1]&amp;lt;e0001000:DWT-M0+ cidr=b105e00d, pidr=4000bb00a, class=14&amp;gt;
INFO:root:[2]&amp;lt;e0002000:BPU cidr=b105e00d, pidr=4000bb00b, class=14&amp;gt;
INFO:root:[1]&amp;lt;f0002000: cidr=b105900d, pidr=4000bb9a3, class=9, devtype=13, devid=0&amp;gt;
INFO:root:CPU core is Cortex-M0
INFO:root:4 hardware breakpoints, 0 literal comparators
INFO:root:2 hardware watchpoints
INFO:root:Telnet: server started on port 4444
INFO:root:GDB server started at port:3333

There is a way to set up a file in udev to remove the need to use sudo to run pyocd. Please see this link on how to do this.

The guide I read recommended using the –persist flag with the pyocd-gdbserver command. I found my serial port communication with the Micro:bit stopped working. Instead of there being a single serial port connection to the Micro:bit, there were several. I suspect the –persist flag kept ‘zombie’ connections alive, causing my code to connect to a dead connection that only existed in the OS’ imagination.

–persist # keep GDB server running even after remote has detached.

As awac explains, this shows that we have access to 4 hardware breakpoints. The server is started at port 3333. This port will be entered into the Eclipse debugger setup, which is explained below.

Set up Eclipse

http://flames-of-code.netlify.com/blog/microbit-cpp-3/ covers setting up a C/C++ Eclipse project with the microbit-samples code downloaded from the Lancaster University github. I am using Eclipse Oxygen at the time of writing this post.

A new project is set up by using File, New, Makefile Project with Existing Code.

Alter the default build command from ‘make’ to ‘yotta build –debug-build’. Get to this by right clicking on the microbit-samples project and selecting ‘Properties’.

Use control-B to build the code. I get a bunch of depreciation warnings that can be ignored.

dynamic exception specifications are deprecated in C++11 [-Wdeprecated]

Configuring the Eclipse C/C++ debugger for use with yotta

The pyOCD site mentions that the plugin ‘Eclipse Embedded Systems Register View’ should be installed. This took me a little while to figure out how to install, so I created a separate post on how to do this here. This plugin is not yet of use for the microbit. I hope to get CMSIS-SVD configuration files from Nordic for the microbit’s microcontroller to be able to make use of the plugin.

I came a little unstuck when setting up the debug session as I could not find the ‘GDB Hardware Debugging’ option when editing my debug configuration. To get that option we need to install the GNU MCU Eclipse plugin from the Eclipse Marketplace. Go to the Help menu and click on ‘Eclipse Marketplace’. Put ‘gnu mcu’ as the search term to find the plugin. This plugin adds the ‘GDB Hardware Debugging’ option to your run configurations which we use when setting up Eclipse.

This allows me set up for the GDB debugger as shown in the screen shots below. Go to Run, Debug configurations.

Double clicking on the heading ‘GDB Hardware Debugging’ and set up the Main, Debugger and Startup tabs as shown below. The C/C++ application is found in the ‘build’ subdirectory, in the microbit-samples directory at:

microbit-samples/build/bbc-microbit-classic-gcc/source/microbit-samples

The Debugger tab specifies the path to the GDB :

/usr/bin/arm-none-eabi-gdb

Enter port ‘3333’, which we noted earlier when starting the gdb server.

In the Startup tab, click on ‘Load image’ and ‘Use File’. Enter

${workspace_loc:/microbit-samples/build/bbc-microbit-classic-gcc/source/microbit-samples-combined.hex}

Initially I had some errors:

Reset command not defined for device 'Generic TCP/IP'

Looking at this Stackoverflow question, I fixed this by also unchecking Reset & Delay and Halt options in the debugger configuration:

Running the Eclipse debugger

Run the command ‘yt clean’ from the command line in your microbit-samples directory to clean out the last build. Then ‘control-b’ in Eclipse to create a fresh build. I feel I should be able to click on the little bug icon on the menu bar to get to the debugger, but this gives me a ‘launch failed. Binary not found.’ window. So I right click on the project and select ‘Debug As’,’Debug Configurations’, ‘microbit-samples Default’ then click on the ‘Debug’ button on the bottom right. I get offered the chance to go to the debug screen, which is a result.

Bash script to mount and unmount a BBC Micro:bit

I develop using the BBC Micro:bit (which I’ll call a microbit from now on) using Linux. To get a new hex file on to the microbit, the microbit has to be mounted on to the file system. Which may seem obvious. But the microbit has a habit of unmounting itself after being programmed. Or not mounting when it is plugged in. So I wrote a script to make things easier. Because I can. To be more accurate, I copied a script from Stackoverflow and made a few minor modifications. Don’t pretend this isn’t how you have written a lot of your scripts.
Find the code at the bottom of this post. Copy and paste it to a file called microbit_manage.sh. Make the file executable (chmod +x ./microbit_manage.sh) and run using either ‘mount’ or ‘unmount’ as an argument. I’ve got these aliased to ‘mm’ and ‘md’ in my .bashrc.

Example usage:

bill@bill ~ $ microbit_manage.sh mount

found one MICROBIT, device: /dev/sdb
MICROBIT was unmounted
Mounted /dev/sdb at /media/bill/MICROBIT.

bill@bill ~ $ microbit_manage.sh unmount

found one MICROBIT, device: /dev/sdb
MICROBIT was mounted
Unmounted /dev/sdb.

Comments and improvements welcome. The script is:

#!/bin/bash
# microbit_manage.sh
# mount and unmount microbit
# modified from https://askubuntu.com/questions>
# v1.0 matt oppenheim October 2017

if [ $# -eq 0 ] 
then
    echo "no argument supplied, use 'mount' or >
    exit 1
fi

# how many MICRO found in udiksctl dump
RESULTS=$(udisksctl dump | grep IdLabel | grep >

0 )     echo "no $MICRO found in 'udkisksctl du>
        exit 0
        ;;

        # if [[ -z $(mount | grep "$DEVICE") &&>
        if [[ -z $(mount | grep "$DEVICE") ]]
        then
            echo "$DEVICELABEL was unmounted"
            if [ $1 == "mount" ]
            then
                udisksctl mount -b "$DEVICE"
                exit 0
            fi
        else
                echo "$DEVICELABEL was mounted"
                if [ $1 == "unmount" ]
                then
                    udisksctl unmount -b "$DEVI>
                    exit 0
                fi
        fi
        ;;
    esac

Getting the BBC Micro:bit radio to work with the mbed online C/C++ compiler

This blog explains how to get the example programs for working with the non-Bluetooth radio on the BBC Micro:bit to compile correctly using the Mbed online C/C++ compiler.

Short story

Two options:

1 Place the line:

#define MICROBIT_BLE_ENABLED 0

in the MicroBit.h library and forget about the config.json file.

Or

2 Create an mbed_app.json file instead of the config.json file with this content:

{
"macros": [ "MICROBIT_BLE_ENABLED=0" ]
}

Long story

 
The Mbed online compiler and the yotta offline compiler for the BBC Micro:bit are explained at the Lancaster University github site here:

https://lancaster-university.github.io/microbit-docs/

I couldn’t get the example radio programs supplied with the online Mbed C/C++ compiler to work with the BBC Micro:bit. These programs did work with the yotta offline compiler. It took a while to figure out that the config.json file supplied with the examples is being ignored by the Mbed online compiler. The BBC Micro:bit has a custom radio setup which does not work when Bluetooth is enabled. The compiler needs to be told that Bluetooth is disabled. In the examples supplied for both the yotta offline compiler and for the mbed online compiler this is done using a config.json file containing:

{ 
    microbit-dal:{
        bluetooth:{
            enabled: 0 
        } 
     } 
}

The example programs are called simple-radio-rx and simple-radio-tx. For the Mbed online compiler, these can be found at:

https://os.mbed.com/teams/microbit/code/microbit-simple-radio-rx/

https://os.mbed.com/teams/microbit/code/microbit-simple-radio-tx/

For the offline yotta compiler the same programs and config.json files can be found at:

https://github.com/lancaster-university/microbit-samples/tree/master/source/examples

The hex files created using the Mbed online compiler resolutely refused to do anything when I loaded them onto the microbits. I figured out that the the config.json file was being ignored by the Mbed online compiler. To disable the Bluetooth through code, place this line:

#define MICROBIT_BLE_ENABLED 0

in the MicroBit.h library. After doing this, the hex files produced by compiling the example programs using the Mbed online compiler ran correctly.

I posted this on the Mbed questions site and an Mbed moderator said that the issue will be fixed:

https://os.mbed.com/questions/79592/BBC-Microbit-how-to-use-the-radio/?compage=1#c29069

A while later, a helpful guy on Stackoverflow advised me to use an mbed_app.json file instead of the config.json file with this content:

{
    "macros": [ "MICROBIT_BLE_ENABLED=0" ]
}

Setting up yotta and C with the BBC Micro:bit by modifying the examples directory

I set up to program the BBC Micro:bit (which I’ll call the microbit from now on) in C/C++ under Linux. I’ve been using micropython to program the boards up to now, but want to leverage the increased performance that using C can give and some of the C libraries that are available for e.g. encryption.

There is good documentation on the Lancaster University microbit github page:

https://lancaster-university.github.io/microbit-docs/

I installed the offline tools as I spend a lot of time working at sea where you can’t always rely on having an internet connection. I got a demo compiled and loaded by following the instructionso n the Lancaster University github site. Now it was time to write my own code. I had a little trouble getting this going, so here’s what I had to do to get my first program compiled and loaded. I did this by modifying the structure of the examples directory that was created by following the github instructions.

I downloaded the github repository linked above into

~/git/microbit-samples

Initially I made a new directory under:

~/git/microbit-samples/source/my_code

Whenever I ran ‘yt build’, I got a weird error referring to one of the bluetooth example programs. Plus yt build took longer than I thought it ought to. So…..

Move

~/git/microbit-samples/source/examples

out of:

~/git/microbit-samples/source/

Put these folders one level above this folder. Only put the main.cpp file into

~/git/microbit-samples/source/

Then run:

yt clean

and

yt build

I copied the file:

~/git/microbit-samples/build//bbc-microbit-classic-gcc/source/microbit-c-combined.hex

to the microbit. After waiting for the flashing LEDs to stop, it worked!

The microbit unmounts itself each time that you load a new hex file. So using the bash script that I detailed in an earlier blog to quickly mount the microbit is a time saver.

This is a quick way of getting started by building on top of the examples directory that most folk will start with.

disclaimer: I loiter in the same department as the authors of the C/C++ BBC Micro:bit repository.

Enabling the analog to digital converter (ADC) on the BBC Micro:bit using C/C++

To get the example ADC code to work on the Lancaster Github site, change the line:

MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);

To:

MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_ANALOG);

I tested this using both the online Mbed compiler and the yotta compiler.

eyeBlink – enabling natural two way conversation with somebody who uses an eyetracker

It can be difficult to tell when a student who uses an eye tracker to operate their communications software is actively using the software. So the temptation is to go and look over their shoulder. The Head Technologist at Beaumont College asked if it is possible to have a light flash to indicate when the communications software is being used. This makes for a more natural two way conversation. You talk to the student and you see the light flashing, so you know that a reply is being composed.

 
After some false starts, I think I have some code that will detect when the software is being used. My script makes an image of the screen each second and looks for a difference. I set a minimum threshold for the difference between the images so that a blinking cursor will not continuously indicate a change.
 
I use a BBC micro:bit to do the flashing as they are cheap, cheerful and reliable. I reckon to have two of these qualities.
 
Please find a picture of Craig, one of the technologists at Beaumont, testing the prototype of the eyeBlink system using a Tobii eyetracker and Sensory Software’s Grid 2 software. You will have to take my word for it that the microbit does indeed flash when the Grid 2 is being used.
Craig testing the eyeBlink hardware at Beaumont College, Lancaster.

how to configure the accelerometer range on the microbit using micropython

This article details how to set the range of sensitivity on the accelerometer on the microbit board using micropython and the i2c interface. I am using v1.7.9 of micropython for the microbit, the mu editor and linux mint v17.
 

After listening to Joe Finney talk about his role in developing the microbit board I realised I could use it for some of my hand gesture assistive technology work. The accelerometer on the microbit board is an MMA8653FC, data sheet here. There are programming notes for this chip here. The default range for this chip is +/-2g. This can be reconfigured to be +/-4g or +/-8g. For some of the students I work with on gesture recognition I need the higher ranges. So I entered the world of microbit i2c programming. I chose the micropython platform as python is always the ‘second best choice’ for any programming application. Actually, I’m a fan of using C for embedded hardware, but in this case using micropython looked to be fastest way of getting a solution. I used the simple mu editor. Long story short, it’s all about syntax. Thanks go to fizban for his example microbit code to interface a microbit with an lcd display using i2c. After reading this code I fixed the mistake(s) I’d been making. The documentation for the i2c microbit micropython is here.

Here’s my working code:

''' microbit i2c communications with onboard accelerometer '''
from microbit import *

ACCELEROMETER = 0x1d
ACC_2G = [0x0e, 0x00]
ACC_4G = [0x0e, 0x01]
ACC_8G = [0x0e, 0x02]
CTRL_REG1_STANDBY = [0x2a, 0x00]
CTRL_REG_1_ACTIVE = [0x2a, 0x01]
PL_THS_REG = [0x14] # returns b'\x84'
PL_BF_ZCOMP = [0x13] # returns b'\44' = 'D'
WHO_AM_I = [0x0d] # returns 0x5a=b'Z'
XYZ_DATA_CFG = [0x0e]

def command(c):
''' send command to accelerometer '''
i2c.write(ACCELEROMETER, bytearray(c))

def i2c_read_acc(register):
''' read accelerometer register '''
i2c.write(ACCELEROMETER, bytearray(register), repeat=True)
read_byte = i2c.read(ACCELEROMETER, 1)
print('read: {}'.format(read_byte))

def main_text():
''' send accelerometer data as a string '''
print('starting main')
counter = 0
while True:
x = accelerometer.get_x()
y = accelerometer.get_y()
z = accelerometer.get_z()
counter = counter + 1
print('{} {} {} {}'.format(counter, x, y, z))
sleep(250)

print("sending i2c commands...")
print('reading PL_BF_ZCOMP :')
print(i2c_read_acc(PL_BF_ZCOMP))
print('reading WHO_AM_I')
print(i2c_read_acc(WHO_AM_I))
# check the initial accelerometer range
print('reading XYZ_DATA_CFG:')
print(i2c_read_acc(XYZ_DATA_CFG))
# change the accelerometer range
command(CTRL_REG1_STANDBY)
command(ACC_4G)
command(CTRL_REG_1_ACTIVE)
print('commands sent')
# check the accelerometer range
print('reading XYZ_DATA_CFG:')
print(i2c_read_acc(XYZ_DATA_CFG))
display.show(Image.MEH)
# main_text()

output:

reading PL_BF_ZCOMP :
read: b'D'
None
reading WHO_AM_I
read: b'Z'
None
reading XYZ_DATA_CFG:
read: b'\x00'
None
commands sent
reading XYZ_DATA_CFG:
read: b'\x01'
None

The onboard accelerometer has an i2c address of 0x1d. There is a good article on how to scan for and verify this address here. I set the variable ACCELEROMETER to be this value in line 4 so that I could refer to it throughout the code without having to remember the hex value. Too many hex values flying around – I’d be bound to make a mistake if I didn’t give them names.

To send a command over i2c, as shown in line 18 of the example code, you need to address the target then send the commands as a bytearray. In this case the target is the accelerometer. Typically we send two bytes to the accelerometer. The first specifies the register we want to change, the second the value we want to write to this register. For example, to set the accelerometer’s range of sensitivity, we need to set the value of the register called XYZ_DATA_CFG to the value that corresponds with the range we are after. The address of this register is 0x0e. To set the +/4G range, we want to set this register to be 0x01. Now the variable I set in line 6 should make sense. Look in the data sheet linked above for more details. Before we can change this register we have to set CTRL_REG1 to be inactive by writing 0x00 to it. After changing the XYZ_DATA_CFG register we have to set CTRL_REG1 to be active again by writing 0x01 to it. This is detailed in the accelerometer application notes which I linked at the start of this article.

If you uncomment the last line, then the raw accelerometer values will stream out. The last column are the values for the z-axis of the accelerometer. Lay the board flat on the table. With the default +/-2g range you will see the z-axis values being around +1024 or -1024 depending on if the board is face up or down. This corresponds to +/-1g on the +/-2g range. Now that the board is set to +/-4g, the values for +/-1 g will be +/-512. The maximum and minimum value for the accelerometer stays as +/-2048, but it is now spread over +/-4g. Similarly, if you go crazy and set the range to be +/-8g, then you will see +/-256 for the z-axis value from the accelerometer for the board laying flat. As you would expect, you have to wave the board harder to get it to max out when you set the sensitivity to the higher ranges compared with the default +/-2g range.

So what about the PL_BF_ZCOMP and WHO_AM_I registers that I read from in lines 43 and 45? These are two read only directories. Reading the values stored in these is a sanity check that the chip is turned on and I have working code. I read the XYZ_DATA_CFG before and after setting it to verify that the sensitivity range has been set. Read up on these registers in the data sheet.

Look at line 23. The repeat=True flag has to be set. This clears the ‘message end’ flag in the write command. The default for this flag is False, which means that the i2c write command has a ‘message end’ flag at the end of it, which terminates the operation. As we want to read from the chip in line 24, we need to not set the ‘message end’ flag. Otherwise you will just read 0xff. Can you guess why? The data line is held high for i2c, so if there is nothing coming out of the chip you are trying to read from, you just read a bunch of ‘1s’. Line 24 means ‘read 1 byte from the device with address ACCELEROMETER’.

Where I initially came unstuck was by sending data as individual bytes, using e.g. b’\x0e’ followed by b’\x02′ to try and change the XYZ_DATA_CFG register. This looks to be valid for the Adafruit implementation of micropython, but I couldn’t get it work.