Unleashing the Power of `ustruct` in MicroPython

MicroPython is a lean and efficient implementation of the Python 3 programming language that includes a small subset of the Python standard library and is optimized to run on microcontrollers and constrained systems. One of the powerful modules in MicroPython is ustruct. The ustruct module provides functions to convert between Python values and C structs represented as Python bytes objects. This is extremely useful when dealing with binary data, such as communication protocols, file formats, or hardware registers. In this blog post, we will explore the fundamental concepts of ustruct in MicroPython, its usage methods, common practices, and best practices.

Table of Contents#

  1. Fundamental Concepts
  2. Usage Methods
  3. Common Practices
  4. Best Practices
  5. Conclusion
  6. References

Fundamental Concepts#

What is a Struct?#

In the C programming language, a struct (structure) is a composite data type that groups together variables of different data types under a single name. For example, a struct could be used to represent a point in 2D space with an x and a y coordinate, where x and y could be integers or floating - point numbers.

ustruct in MicroPython#

The ustruct module in MicroPython allows you to work with binary data in a similar way to how you would work with C structs. It provides functions to pack Python values into binary data and unpack binary data back into Python values.

Format Strings#

Format strings are used to specify the layout of the data in the struct. Each character in the format string represents a different data type. For example:

  • 'b': Signed char (1 byte)
  • 'B': Unsigned char (1 byte)
  • 'h': Signed short (2 bytes)
  • 'H': Unsigned short (2 bytes)
  • 'i': Signed int (4 bytes)
  • 'I': Unsigned int (4 bytes)
  • 'f': Float (4 bytes)
  • 'd': Double (8 bytes)

Usage Methods#

ustruct.pack()#

The ustruct.pack() function takes a format string and a sequence of values, and returns a bytes object containing the packed data.

import ustruct
 
# Pack an integer and a float
packed_data = ustruct.pack('if', 123, 3.14)
print(packed_data)

In this example, the format string 'if' indicates that we are packing an integer ('i') followed by a float ('f').

ustruct.unpack()#

The ustruct.unpack() function takes a format string and a bytes object, and returns a tuple containing the unpacked values.

import ustruct
 
packed_data = ustruct.pack('if', 123, 3.14)
unpacked_values = ustruct.unpack('if', packed_data)
print(unpacked_values)

ustruct.calcsize()#

The ustruct.calcsize() function takes a format string and returns the size (in bytes) of the struct described by the format string.

import ustruct
 
size = ustruct.calcsize('if')
print(size)

Common Practices#

Reading Binary Files#

When working with binary files, ustruct can be used to read and interpret the data.

import ustruct
 
# Open a binary file
with open('data.bin', 'rb') as f:
    # Read the first 8 bytes (an int and a float)
    data = f.read(ustruct.calcsize('if'))
    values = ustruct.unpack('if', data)
    print(values)

Communication Protocols#

In communication protocols, data is often sent in binary format. ustruct can be used to pack and unpack the data according to the protocol's specifications.

import ustruct
import machine
import time
 
# Assume we are using UART for communication
uart = machine.UART(0, 9600)
 
# Pack data to send
data_to_send = ustruct.pack('if', 123, 3.14)
uart.write(data_to_send)
 
# Receive data
time.sleep(1)
received_data = uart.read(ustruct.calcsize('if'))
if received_data:
    unpacked = ustruct.unpack('if', received_data)
    print(unpacked)

Best Practices#

Error Handling#

When using ustruct.unpack(), make sure that the length of the input bytes object matches the size specified by the format string. Otherwise, a struct.error will be raised.

import ustruct
 
try:
    packed_data = ustruct.pack('if', 123, 3.14)
    # Try to unpack with incorrect format
    unpacked = ustruct.unpack('i', packed_data)
except ustruct.error as e:
    print(f"Error: {e}")

Use Descriptive Format Strings#

When working with complex data structures, use descriptive variable names for format strings to improve code readability.

import ustruct
 
# Define a format string for a custom struct
SENSOR_DATA_FORMAT = 'iff'  # One int and two floats
 
# Pack sensor data
sensor_values = (1, 2.5, 3.7)
packed_sensor_data = ustruct.pack(SENSOR_DATA_FORMAT, *sensor_values)
 
# Unpack sensor data
unpacked_sensor_data = ustruct.unpack(SENSOR_DATA_FORMAT, packed_sensor_data)
print(unpacked_sensor_data)

Conclusion#

The ustruct module in MicroPython is a powerful tool for working with binary data. It allows you to easily convert between Python values and C structs, which is essential when dealing with binary file formats, communication protocols, and hardware registers. By understanding the fundamental concepts, usage methods, common practices, and best practices, you can efficiently use ustruct in your MicroPython projects.

References#

2025-10