MicroPython 'usys' Module

Introduction
Module 'usys' Listing
Functions and Constants:
MicroPython Tutorial Links

Introduction

MicroPython is a 'slim' version of the ever popular Python programming language. With its much smaller footprint it is an effective and easily learnt language for programming microcontrollers.

The BBC micro:bit was originally designed and mass produced as an educational device. However many enthusiasts have discovered this interesting little device and it is increasingly becoming explored by microcontroller hobbyists.

The version of MicroPython ported to the micro:bit is an even smaller subset of Python but is perfectly adequate to squeeze interesting functionality out of this device.

The usys MicroPython module is a very small subset of the parent Python sys module. Indeed, of the items from the module that have made the MicroPython port, more than a couple have very little meaning on the micro:bit platform.

The MicroPython module may also be referred to by the Python name sys. However for consistency this should be resisted. The 'u' prefix in usys represents the micro from microcontrollers.

Module 'usys' Listing

The following is an exhaustive list in alphabetical order of all the items from the usys module. Each item has a link to its full description in the categorised sections following.

argv	byteorder	exit()
implementation	maxsize	modules
path	platform	print_exception()
version	version_info

The items from the module can be broken up into three broad categories: System, MicroPython and Coding.

An import statement is necessary before calling anything from this module. This is of the following form:


import usys

System

byteorder

Returns the byte order of the system:'little' endian or 'big' endian

A big-endian system stores the most significant byte (MSB) of the data at the smallest memory address and the least significant byte (LSB) at the largest.

A small-endian system operates in reverse with the LSB stored at the smallest address and the MSB stored at the highest address. An example best explains this:


Consider the base₁₀ (decimal) value: 123456789
It has the hexadecimal value: 0x075BCD15
This can be broken down into 4 x bytes: 07, 5B, CD, 15
                                       MSB → → → → → LSB

The order that these four bytes are stored in memory
depends on whether the ordering is little-endian
or big-endian.

Memory Location: x01 x02 x03 x04 
     big-endian:  07  5B  CD  15
  little-endian:  15  CD  5B  07

Running this on the micro:bit yields the following:


Example
import usys
print(usys.byteorder)

Output:
little

Thus the micro:bit uses the small-endian byte order.

path

Returns a mutable list of directories to search for imported modules.

This makes little sense on the micro:bit since it has a completely flat file system with no directories allowed.


Example
import usys
print(usys.path)

Output:
['', '.frozen']

The ''.frozen' entry indicates that the program might be found compiled and embedded in the firmware image.

platform

Returns the name of the platform that MicroPython is running on.


Example
import usys
print(usys.platform)

Output:
microbit

MicroPython

implementation

Returns a tuple with information about the current MicroPython implementation. The following two fields are returned:

name - string 'micropython'
version - MicroPython release level (major, minor, micro)


Example
import usys
print(usys.implementation)

Output:
(name='micropython', version=(1, 18, 0))

Thus this micro:bit is running MicroPython release 1.18.0. This is not to be confused with the version of Python that this port has been based upon - see usys.version below.

version

Returns the Python language version that this implementation conforms to, as a string - 'major. minor. micro'. This is basically the same as usys.version_info which returns the same information as a tuple.


Example
import usys
print(usys.version)

Output:
3.4.0

Thus from usys.implementation and usys.version this micro:bit is running MicroPython release 1.18.0 which has been based on Python V3.4.0.

version_info

Returns the Python language version that this implementation conforms to, as a tuple of ints - (major, minor, micro). This is basically the same as usys.version which returns the information as a string.


Example
import usys
print(usys.version_info)

Output:
(3, 4, 0)

maxsize

Returns the largest value a variable of data type Py_ssize_t can store. It is the MicroPython platform's pointer that dictates the maximum size of lists and strings. The size value returned by usys.maxsize depends on the platform architecture.


Example
import usys
print(usys.maxsize)

Output:
2147483647

This value returned by the micro:bit of 2147483647 is 32-bit i.e.
2**31 - 1
= 2147483647

Coding

argv

Returns a mutable list of arguments the current program was started with. This function has no real value as there is no simple way to pass command line arguments to a MicroPython program running on a micro:bit.


Example
import usys
print(usys.argv)

Output:
[]

exit()


Example
 # Demonstrate usys.exit()

import usys

def is_number(value):
    # Returns True if value is numerical
    x = isinstance(value, int)
    y = isinstance(value, float)
    return bool(x | y)

def Add(List):
    # iterates through a list of
    # numbers and sums them.
    # If a non-numerical value
    # is found an error message is
    # printed and the program terminates.
    sum = 0
    for i in List:
        if is_number(i):
            sum += i
        else:
            print(i, ' is not numerical')
            usys.exit()

L = [1, 2, 'Hello']            
print('Sum is:', Add(L))

Output:
Hello  is not numerical

This example program attempts to sum all the elements of the list L. When the value'Hello' is reached, it is recognised as being non-numerical and usys.exit() is executed resulting in the program printing an error message and terminating.

modules

Returns a dictionary of loaded modules. On some MicroPython ports, it may not include builtin modules.

To test this function a user module must be prepared. Enter the following code into the Mu Editor and save the file as numerical.py.


def is_number(value):
    # Returns True if value is numerical
    x = isinstance(value, int)
    y = isinstance(value, float)
    return bool(x | y)

Using the Files button on the Mu toolbar copy this file into the micro:bit's file system.


Example
import numerical
import usys

L = [1, 3.45, 'Hello', 3e10]
for i in L:
    if numerical.is_number(i):
        print(i, 'is numerical')
    else:
        print(i, 'is not numerical')

# Test usys.modules
print(usys.modules)

Output:
1 is numerical
3.45 is numerical
Hello is not numerical
3e+10 is numerical
'numerical': <module 'numerical'>

Note that usys.modules returns the name of the imported user module numerical but not the imported builtin module usys.

print_exception(error[, file)

Print exception with a traceback to a file-like object file (or stdout by default). This sounds complicated but is easily understood by example.


Example
import usys
try:
    1/0
except Exception as e:
    usys.print_exception(e)
    
print('Oops!')

Output:
Traceback (most recent call last):
  File "main.py", line 3, in <module>
ZeroDivisionError: divide by zero
Oops!

Because the ZeroDivisionError exception was caught the program did not terminate at the attempt to divide by zero. The final statement of the program did execute.

< Previous

Next >