{"id":774,"date":"2021-04-08T14:26:05","date_gmt":"2021-04-08T14:26:05","guid":{"rendered":"https:\/\/picockpit.com\/raspberry-pi\/?p=774"},"modified":"2023-11-23T02:13:08","modified_gmt":"2023-11-23T02:13:08","slug":"c-extension-for-micropython-on-raspberry-pi-pico","status":"publish","type":"post","link":"https:\/\/picockpit.com\/raspberry-pi\/c-extension-for-micropython-on-raspberry-pi-pico\/","title":{"rendered":"C extension for MicroPython on Raspberry Pi Pico"},"content":{"rendered":"\n

This is a guide on how to write and run a basic C extension for MicroPython on the Raspberry Pi Pico. I will cover reasons for extending MicroPython, how to write the extension module, how to compile it and how to install it on the Pico. If you want to read more about this topic, please refer to https:\/\/docs.micropython.org\/en\/latest\/develop\/extendingmicropython.html<\/a><\/p>\n\n\n\n

Introduction<\/h2>\n

Why extend MicroPython?<\/h3>\n

There can be multpiple reasons why you might want to extend MicroPython. Since it is a trimmed down version of Python, MicroPython is not performing very well when it comes to computationally heavy tasks (similar to Python). C on the other hand is really well suited for such tasks. A C extension for Micropython enables you to perform those computations through C language and use the results in MicroPython. This can speed up some processes by an order of magnitudes.<\/p>\n

A second reason might be, that you want to interface some hardware which uses a C API from within MicroPython. <\/p>\n

Types of MicroPython C extensions<\/h3>\n

There are to different ways to extend MicroPython : external C modules and native machine code in .mpy files.<\/p>\n

To run an external C module you need to recompile it into the MicroPython firmware. This is a rather complicated process, which is why this guide will focus on the second alternative. If you are however interested in this approach, you can read more about it on these webpages:                https:\/\/docs.micropython.org\/en\/latest\/develop\/cmodules.html<\/a>                      https:\/\/www.raspberrypi.org\/forums\/viewtopic.php?t=300352<\/a><\/p>\n

The .mpy is a file that stores compiled native machine code and can be linked dynamically. This makes it much more flexible since you don’t need to recompile the entire MicroPython firmware.<\/p>\n\n\n\n

Write the extension module<\/h2>\n\n\n\n

Writing the extension module is the easiest part of extending MicroPython. I will show you how to do it by looking at a simple example. To start, we will create a new directory called factfib<\/em>. Open a new terminal window, cd into the new directory and create a new file called factfib.c<\/em>. If you created the directory on a Raspberry Pi under Dekstop, the command looks like this.<\/p>\n\n\n\n

<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
cd<\/span> <\/span>~\/<\/span>Desktop<\/span>\/<\/span>factfib<\/span><\/span>\n<\/span>\ntouch<\/span> <\/span>factfib<\/span>.<\/span>c<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Open factfib.c<\/em><\/span> in your favorite text editor and enter the following code:<\/span><\/span><\/span><\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
#<\/span>include<\/span> <\/span>"<\/span>py\/dynruntime.<\/span>h<\/span><\/span>\n<\/span>\nSTATIC<\/span> <\/span>mp_int_t<\/span> <\/span>factorial_helper<\/span>(<\/span>mp_int_t<\/span> <\/span>x<\/span>) <\/span>{<\/span><\/span>\n   <\/span>if<\/span> (<\/span>x<\/span> <\/span><<\/span> <\/span>1<\/span>) <\/span>{<\/span><\/span>\n      <\/span>return<\/span> <\/span>1<\/span>;<\/span><\/span>\n   <\/span>}<\/span><\/span>\n   <\/span>return<\/span> <\/span>x<\/span>*<\/span>factorial_helper<\/span>(<\/span>x<\/span>-<\/span>1<\/span>)<\/span>;<\/span><\/span>\n}<\/span><\/span>\n<\/span>\nSTATIC<\/span> <\/span>mp_obj_t<\/span> <\/span>factorial<\/span>(<\/span>mp_obj_t<\/span> <\/span>x_obj<\/span>) <\/span>{<\/span><\/span>\n   <\/span>mp_int_t<\/span> <\/span>x<\/span> <\/span>=<\/span> <\/span>mp_obj_get_int<\/span>(<\/span>x_obj<\/span>)<\/span>;<\/span><\/span>\n   <\/span>mp_int_t<\/span> <\/span>rslt<\/span> <\/span>=<\/span> <\/span>factorial_helper<\/span>(<\/span>x<\/span>)<\/span>;<\/span><\/span>\n   <\/span>return<\/span> <\/span>rslt<\/span>;<\/span><\/span>\n}<\/span><\/span>\n<\/span>\nSTATIC<\/span> <\/span>MP_DEFINE_CONST_FUN_OBJ_1<\/span>(<\/span>factorial_obj<\/span>,<\/span> <\/span>factorial<\/span>)<\/span>;<\/span><\/span>\n<\/span>\nSTATIC<\/span> <\/span>mp_int_t<\/span> <\/span>fibonacci_helper<\/span>(<\/span>mp_int_t<\/span> <\/span>x<\/span>) <\/span>{<\/span><\/span>\n   <\/span>if<\/span> (<\/span>x<\/span> <\/span><=<\/span> <\/span>0<\/span>) <\/span>{<\/span><\/span>\n      <\/span>return<\/span> <\/span>0<\/span>;<\/span><\/span>\n   <\/span>}<\/span><\/span>\n   <\/span>else<\/span> <\/span>if<\/span> (<\/span>x<\/span> <\/span>==<\/span> <\/span>1<\/span>) <\/span>{<\/span><\/span>\n      <\/span>return<\/span> <\/span>1<\/span>;<\/span><\/span>\n   <\/span>}<\/span><\/span>\n   <\/span>else<\/span> <\/span>{<\/span><\/span>\n      <\/span>return<\/span> (<\/span>fibonacci_helper<\/span>(<\/span>x<\/span>-<\/span>1<\/span>) <\/span>+<\/span> <\/span>fibonacci_helper<\/span>(<\/span>x<\/span>-<\/span>2<\/span>))<\/span>;<\/span><\/span>\n   <\/span>}<\/span><\/span>\n}<\/span><\/span>\n<\/span>\nSTATIC<\/span> <\/span>mp_obj_t<\/span> <\/span>fibonacci<\/span>(<\/span>mp_obj_t<\/span> <\/span>x_obj<\/span>) <\/span>{<\/span><\/span>\n   <\/span>mp_int_t<\/span> <\/span>x<\/span> <\/span>=<\/span> <\/span>mp_obj_get_int<\/span>(<\/span>x_obj<\/span>)<\/span>;<\/span><\/span>\n   <\/span>mp_int_t<\/span> <\/span>rslt<\/span> <\/span>=<\/span> <\/span>fibonacci_helper<\/span>(<\/span>x<\/span>)<\/span>;<\/span><\/span>\n   <\/span>return<\/span> <\/span>mp_obj_new_int<\/span>(<\/span>rslt<\/span>)<\/span>;<\/span><\/span>\n}<\/span><\/span>\n<\/span>\nSTATIC<\/span> <\/span>MP_DEFINE_CONST_FUN_OBJ_1<\/span>(<\/span>fibonacci_obj<\/span>,<\/span> <\/span>fibonacci<\/span>)<\/span>;<\/span><\/span>\n<\/span>\nmp_obj_t<\/span> <\/span>mpy_init<\/span>(<\/span>mp_obj_fun_bc_t<\/span> <\/span>*<\/span>self<\/span>,<\/span> <\/span>size_t<\/span> <\/span>n_args<\/span>,<\/span> <\/span>size_t<\/span> <\/span>n_kw<\/span>,<\/span> <\/span>mp_obj_t<\/span> <\/span>*<\/span>args<\/span>) <\/span>{<\/span><\/span>\n   <\/span>MP_DYNRUNTIME_INIT_ENTRY<\/span><\/span>\n<\/span>\n   <\/span>mp_store_global<\/span>(<\/span>MP_QSTR_factorial<\/span>,<\/span> <\/span>MP_OBJ_FROM_PTR<\/span>(<\/span>&<\/span>factorial_obj<\/span>))<\/span>;<\/span><\/span>\n   <\/span>mp_store_global<\/span>(<\/span>MP_QSTR_fibonacci<\/span>,<\/span> <\/span>MP_OBJ_FROM_PTR<\/span>(<\/span>&<\/span>fibonacci_obj<\/span>))<\/span>;<\/span><\/span>\n<\/span>\n   <\/span>MP_DYNRUNTIME_INIT_EXIT<\/span><\/span>\n}<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Let me explain the code above: In MicroPython and Python, every variable is an object. Therefore in C we represent them as mp_obj_t<\/em>. But a C program can only work with C type variables, which is why we need to transform the object into a C type. This is called Marshalling and MicroPython provides functions to extract any C type from an object.<\/p>\n\n\n\n
Build the extension<\/h2>\n\n\n\n
We build the extension into a .mpy file by using a Makefile. But we need to set up a few things first. Make sure your terminal is still opened in the factfib<\/em> directory. Then clone the MicroPython GitHub repository.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
sudo<\/span> <\/span>apt<\/span>-<\/span>get<\/span> <\/span>install<\/span> <\/span>build<\/span>-<\/span>essential<\/span> <\/span>libreadline<\/span>-<\/span>dev<\/span> <\/span>libffi<\/span>-<\/span>dev<\/span> <\/span>git<\/span> <\/span>pkg<\/span>-<\/span>config<\/span> <\/span>gcc<\/span>-<\/span>arm<\/span>-<\/span>none<\/span>-<\/span>eabi<\/span> <\/span>libnewlib<\/span>-<\/span>arm<\/span>-<\/span>none<\/span>-<\/span>eabi<\/span><\/span>\n<\/span>\ngit<\/span> <\/span>clone<\/span> <\/span>--<\/span>recurse<\/span>-<\/span>submodules<\/span>\u00a0https<\/span>:<\/span>\/\/github.com\/micropython\/micropython.git<\/span><\/span>\n<\/span>\npip3<\/span>\u00a0<\/span>install<\/span>\u00a0<\/span>'<\/span>pyelftools>=0.25<\/span>'<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
These installations will take a while, if you want to save time and you know what you are doing, you only need to clone the \/py and \/tools directory from the micropython repository and put them inside a micropython<\/em> folder inside the factfib<\/em> folder (skip the second command).<\/p>\n\n\n\n
While the installation is running we can use the time to write the Makefile. Simply execute<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
touch<\/span> <\/span>Makefile<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
and open the newly created file in a text editor.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
MPY_DIR<\/span> <\/span>=<\/span> <\/span>micropython<\/span><\/span>\n<\/span>\nMOD<\/span> <\/span>=<\/span> <\/span>factfib<\/span><\/span>\n<\/span>\nSRC<\/span> <\/span>=<\/span> <\/span>factfib<\/span>.<\/span>c<\/span><\/span>\n<\/span>\nARCH<\/span> <\/span>=<\/span> <\/span>armv7m<\/span><\/span>\n<\/span>\ninclude<\/span> <\/span>$<\/span>(<\/span>MPY_DIR<\/span>)<\/span>\/<\/span>py<\/span>\/<\/span>dynruntime<\/span>.<\/span>mk<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
You might have noticed that we set the ARCH <\/em>variable to armv7m<\/em> although the pico is armv6m<\/em>. We have to do this because the armv6m<\/em> architecture is (at the moment I’m writing this article) not supported by the dynruntime.mk<\/em> tool.<\/p>\n\n\n\n
But luckily we can still compile a working extension for the Pico. We just need to modify the dynruntime.mk <\/em>file, which should be located under micropython\/py\/dynruntime.mk. <\/em>Open it and under Architecture configuration in armv7m find the CFLAGS variable (should be line 64). Change -mcpu=cortex-m3<\/em> to -mcpu=cortex-m0<\/em> and save the file.<\/p>\n\n\n
\n
\"chnge<\/figure>\n<\/div>\n\n\n
Then after everything is installed execute<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
make<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
and the factfib.mpy<\/em> file will be created.<\/p>\n\n\n\n
Install and test the extension<\/h2>\n\n\n\n
The last step is installing and testing. For this we utilize the filesystem that Micropython creates on the Raspberry Pi Pico. First we need to flash the Pico with the MicroPython firmware. the easiest way to do this is to use the Thonny IDE (preinstalled on Raspbian\/Raspberry Pi OS).<\/p>\n\n\n\n
If you are not using a Raspberry Pi to programm your Pico or if you never used MicroPython on the Pico before then please refer to the getting started with MicroPython guide by Raspberry Pi https:\/\/www.raspberrypi.org\/documentation\/rp2040\/getting-started\/#getting-started-with-micropython<\/a><\/p>\n\n\n\n
If you are using Windows you should check out this blog Post about the Raspberry Pi Pico and MicroPython on Windows https:\/\/picockpit.com\/raspberry-pi\/raspberry-pi-pico-and-micropython-on-windows\/<\/a><\/p>\n\n\n\n
Close Thonny after you have flashed your Pico with the MicroPython firmware and install rshell. We use rshell to access the filesystem from the command line.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
sudo<\/span> <\/span>pip3<\/span> <\/span>install<\/span> <\/span>rshell<\/span><\/span>\nrshell<\/span> <\/span>--<\/span>version<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
This prints the rhsell version if everything is set up correctly. Then unplug the pico and plug it in again (without holding BOOTSEL button) to make sure nothing is trying to access the file system. Now we need to execute<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
rshell<\/span> <\/span>-<\/span>p<\/span> <\/span>\/<\/span>dev<\/span>\/<\/span>ttyACM0<\/span> <\/span>--<\/span>buffer<\/span>-<\/span>size<\/span> <\/span>512<\/span><\/span>\n<\/span>\ncp<\/span> <\/span>factfib<\/span>.<\/span>mpy<\/span> <\/span>\/<\/span>pyboard<\/span>\/<\/span>factfib<\/span>.<\/span>mpy<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
To test the installation you could use either rshell or the Thonny IDE to save your .py<\/em> files on the Pico but I will demonstrate how to use the MicroPython interpreter over the minicom.<\/p>\n\n\n\n
So first press Ctrl+c<\/em> to leave rshell and then install minicom via<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
sudo<\/span> <\/span>apt<\/span> <\/span>install<\/span> <\/span>minicom<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
now we can access the Picos REPL (Read-eval-print loop)<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
minicom<\/span> <\/span>-<\/span>o<\/span> <\/span>-<\/span>D<\/span> <\/span>\/<\/span>dev<\/span>\/<\/span>ttyACM0<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
The three closing angle brackets >>> indicate that the MicroPython interpreter is running. Now we can import our extension and work with it as usual.<\/p>\n\n\n\n
<\/circle><\/circle><\/circle><\/g><\/svg><\/span><\/path><\/path><\/svg><\/span>
>>><\/span> <\/span>import<\/span> <\/span>factfib<\/span> <\/span>as<\/span> <\/span>ff<\/span><\/span>\n<\/span>\n>>> <\/span>ff<\/span>.<\/span>factorial<\/span>(5)<\/span><\/span>\n<\/span>\n>>> 120<\/span><\/span>\n<\/span>\n>>> <\/span>ff<\/span>.<\/span>fibonacci<\/span>(7)<\/span><\/span>\n<\/span>\n>>> 13<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Congratulations! You have created your first MicroPython C extension for the Pico! The next step is to learn how to write and compile more complex modules. A good way to start is by testing how the Marshalling of lists and dicts works (see the Marshalling webpage from above). <\/p>\n\n\n\n
If you have any questions regarding this post, feel free to write a comment.<\/p>\n
This webpage by Oliver Robson is really helpful for Marshalling https:\/\/mpy-c-gen.oliverrobson.tech\/<\/a>. Furthermore you can find Marshalling examples in the MicroPython documentation https:\/\/docs.micropython.org\/en\/latest\/develop\/natmod.html<\/a>. I advise you to read this article if you need further explanation.<\/p>\n\n\n\n