If you're converting code from Arduino/C or C++ to Python there are a few subtle and not-so-subtle issues to worry about.  One major difference between these languages is that the type of a variable is always known in Arduino and it can do certain optimizations and checks automatically for you.  In Python a variable can be any type and freely change between them--this flexibility makes Python easier to program, but can cause some trouble if you're moving over code that expects rigid and fixed types.  In particular manipulating numbers and numeric values in Python sometimes has to be done a bit different than Arduino. 

Check out the following tips below:

Unsigned Integers

One major stumbling block in converting Arduino to Python code is that there is no concept of an unsigned (or only positive) integer in Python.  In Python all numbers are arbitrarily large positive & negative values.  In Arduino you can choose if a number should only be positive values from 0-255 (a byte or uint8_t type), 0-65535 (an unsigned 16-bit value), and more.  You can run into very subtle bugs, like this code in Arduino:

uint8_t foo = 255;

Serial.println(foo + 1);

Would not behave the same as this code in Python:

foo = 255

print(foo + 1)

Try it out to see for yourself!  The Python code will print 256 whereas the Arduino code will print 0!  If you're blindly copying Arduino code to Python this is a very subtle bug that could mean your arithmetic and math doesn't work the way you expect.  At best you might run into an error or unexpected exception, and at worst you might spend days and weeks chasing down impossible to understand issues!

How can you simulate the behavior of an unsigned type like the above in Python?  It turns out if you mask off the bits you care about then Python will get a result that you expect, so the equivalent Python code would be:

foo = 255

print((foo + 1) & 0xFF)

The "& 0xFF" bit is a boolean and operation which tells Python to only look at the lower 8 bits of the numeric value and ignore everything else.  Once Python looks at the low bits of the value 256 it will see the value 0 which is what you would expect when 255 overflows with the addition of 1.  Be very careful to watch for all uses of unsigned types in Arduino code and make sure your Python code masks out the appropriate size bits after it performs operations on them.

Struct Module

Another issue with converting from Arduino to Python is that again Python doesn't have a concept of fixed numeric types.  This means it can be difficult to take the bytes of a register that you read from a device and interpret them as a fixed size number (like a 16-bit unsigned integer, 8-bit signed integer, 32-bit floating point value, etc.).  Luckily there's an entire module in Python that's built to do this conversion for you, the struct module.  In CircuitPython and MicroPython the struct module is available (sometimes called ustruct in older builds) and you can use its pack and unpack functions to convert bytes to and from different size numeric types.

Division Is Floating Point

Another issue that cause very subtle bugs in converting Arduino to Python code is the user of division.  Consider this line in Arduino:

int foo = 10;

Serial.println(foo / 3);

And the similar lines of code in Python:

foo = 10

print(foo / 3)

If you run both you'll get very different results! In Arduino you'll see 3 and in Python you'll see 3.33333!  Although both numbers are similar, the Python version is performing division with floating point by default.  This means you can get fractional values where you might not have expected them otherwise.  At best you might get an exception (like if performing division to manipulate bytes and bits) and at worst you'll create code that runs without error but gives you the completely wrong result.

Luckily in Python you can fix this by telling Python to explicitly perform integer division.  Do this by specifying the double divide operator, //, like:

foo = 10

print(foo // 3)

Now you'll see the expected result of 3 from the Python code.  The double divide will force Python to perform integer division.  As you port Arduino code to Python you need to be very careful to see where the Arduino code is performing division on integer types (even implicitly!) and use the double divide operator.  Don't use double divide everywhere though because in some cases you actually want floating point division.  Carefully review each use of division to see where integer vs. floating point is necessary.

Timing Critical Code

Another potential stumbling block when converting Arduino to Python code is dealing with blocks of code that are timing critical.  That is when a section of code has to operate within a very fast or small window of time.  For example when telling NeoPixels what color to light up a very fast signal needs to be generated.  This signal is so fast it's actually too slow to try doing it in an interpreted language like CircuitPython and MicroPython.  The overhead of the Python interpreter converting the Python code into machine code is just too high and the performance can't be matched compared to compiled languages like Arduino.

So what can you do when you run into timing critical code?  Unfortunately there's no single fix or magic bullet to solve the problem.  You'll need to understand what the code is doing and if there are ways it might be written to depend less on performance (are there peripherals or other parts of the hardware that can do the same job with less performance demands?).  You can also consider modifying the Python firmware to include C functions that don't have as many timing constraints, but this is an advanced topic and not something that's easy or possible to do purely in a driver (it requires building an entirely new CircuitPython or MicroPython firmware).

The key thing about performance is to look for where it matters before you get deep into porting driver code.  Carefully review the Arduino code and look for sections which mention critical sections, timing constraints, etc.  Also review the datasheet and if your device isn't using a standard protocol like SPI, I2C, etc. which most hardware will natively support, then you might run into performance issues trying to emulate or 'bit bang' a protocol in Python code.  However some devices don't care about speed and even slow Python code is just fine to talk to them--every device is different so be prepared to spend time investigating the devices you're porting and their requirements for speed and timing critical code.

Memory Usage

In Python you don't typically need to manage memory as the interpreter is smart about understanding when memory is used and unused.  However there is still a limited amount of memory available and this can cause problems for your driver code.  As mentioned before at some point (typically 200-300 lines of code) a pure text .py file becomes too big for your board to load and process in memory.  For this issue you typically want to convert the file to a binary .mpy version--this file will use less memory when loaded by the interpreter.

Within your driver code you might run into memory issues too, like if you're creating very large buffers or lots of variables.  There's no easy fix for this--memory is finite and you typically can't add more.  If you need more memory you need to find ways to reduce other memory usage.  Sometimes you can remove unused variables, functions, etc.  Sometimes you might need to remove functionality entirely and strip a driver down to just the core features.  There's no easy fix but be aware memory can be a significant issue as you port complex drivers and code to Python!

This guide was first published on Oct 16, 2017. It was last updated on Mar 08, 2024.

This page (Gotchas) was last updated on Oct 12, 2017.

Text editor powered by tinymce.