This is the documentation for the latest development branch of MicroPython and may refer to features that are not available in released versions.

If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

uctypes – Access binary data in a structured way.

Access binary data in a structured way.

This module implements “foreign data interface” for MicroPython. The idea behind it is similar to CPython’s ctypes modules, but the actual API is different, streamlined and optimized for small size. The basic idea of the module is to define data structure layout with about the same power as the C language allows, and then access it using familiar dot-syntax to reference sub-fields.

Attributes

`ARRAY`	Type constants for pointers and arrays. Note that there is no explicit
`BIG_ENDIAN`	Layout type for a big-endian packed structure.
`FLOAT32`	Floating-point types for structure descriptors.
`FLOAT64`	Floating-point types for structure descriptors.
`INT16`	Integer types for structure descriptors. Constants for 8, 16, 32,
`INT32`	Integer types for structure descriptors. Constants for 8, 16, 32,
`INT64`	Integer types for structure descriptors. Constants for 8, 16, 32,
`INT8`	Integer types for structure descriptors. Constants for 8, 16, 32,
`LITTLE_ENDIAN`	Layout type for a little-endian packed structure. (Packed means that every
`NATIVE`	Layout type for a native structure - with data endianness and alignment
`PTR`	Type constants for pointers and arrays. Note that there is no explicit
`UINT16`	Integer types for structure descriptors. Constants for 8, 16, 32,
`UINT32`	Integer types for structure descriptors. Constants for 8, 16, 32,
`UINT64`	Integer types for structure descriptors. Constants for 8, 16, 32,
`UINT8`	Integer types for structure descriptors. Constants for 8, 16, 32,
`VOID`	`VOID` is an alias for `UINT8`, and is provided to conveniently define

Classes

struct

Instantiate a "foreign data structure" object based on structure address in

Functions

`addressof`(→ int)	Return address of an object. Argument should be bytes, bytearray or
`bytearray_at`(→ bytearray)	Capture memory at the given address and size as bytearray object.
`bytes_at`(→ bytes)	Capture memory at the given address and size as bytes object. As bytes
`sizeof`(→ int)	Return size of data structure in bytes. The struct argument can be

Module Contents

class uctypes.struct(addr, descriptor, layout_type=NATIVE): Instantiate a “foreign data structure” object based on structure address in memory, descriptor (encoded as a dictionary), and layout type (see below).

uctypes.addressof(obj) → int: Return address of an object. Argument should be bytes, bytearray or other object supporting buffer protocol (and address of this buffer is what actually returned).

uctypes.bytearray_at(addr, size) → bytearray: Capture memory at the given address and size as bytearray object. Unlike bytes_at() function above, memory is captured by reference, so it can be both written too, and you will access current value at the given memory address.

uctypes.bytes_at(addr, size) → bytes: Capture memory at the given address and size as bytes object. As bytes object is immutable, memory is actually duplicated and copied into bytes object, so if memory contents change later, created object retains original value.

uctypes.sizeof(struct, layout_type=NATIVE) → int: Return size of data structure in bytes. The struct argument can be either a structure class or a specific instantiated structure object (or its aggregate field).

uctypes.ARRAY: Incomplete: Type constants for pointers and arrays. Note that there is no explicit constant for structures, it’s implicit: an aggregate type without PTR or ARRAY flags is a structure.

uctypes.BIG_ENDIAN: Incomplete: Layout type for a big-endian packed structure.

uctypes.FLOAT32: Incomplete: Floating-point types for structure descriptors.

uctypes.FLOAT64: Incomplete: Floating-point types for structure descriptors.

uctypes.INT16: int: Integer types for structure descriptors. Constants for 8, 16, 32, and 64 bit types are provided, both signed and unsigned.

uctypes.INT32: int: Integer types for structure descriptors. Constants for 8, 16, 32, and 64 bit types are provided, both signed and unsigned.

uctypes.INT64: int: Integer types for structure descriptors. Constants for 8, 16, 32, and 64 bit types are provided, both signed and unsigned.

uctypes.INT8: int: Integer types for structure descriptors. Constants for 8, 16, 32, and 64 bit types are provided, both signed and unsigned.

uctypes.LITTLE_ENDIAN: bytes: Layout type for a little-endian packed structure. (Packed means that every field occupies exactly as many bytes as defined in the descriptor, i.e. the alignment is 1).

uctypes.NATIVE: Incomplete: Layout type for a native structure - with data endianness and alignment conforming to the ABI of the system on which MicroPython runs.

uctypes.PTR: Incomplete: Type constants for pointers and arrays. Note that there is no explicit constant for structures, it’s implicit: an aggregate type without PTR or ARRAY flags is a structure.

uctypes.UINT16: int: Integer types for structure descriptors. Constants for 8, 16, 32, and 64 bit types are provided, both signed and unsigned.

uctypes.UINT32: int: Integer types for structure descriptors. Constants for 8, 16, 32, and 64 bit types are provided, both signed and unsigned.

uctypes.UINT64: int: Integer types for structure descriptors. Constants for 8, 16, 32, and 64 bit types are provided, both signed and unsigned.

uctypes.UINT8: int: Integer types for structure descriptors. Constants for 8, 16, 32, and 64 bit types are provided, both signed and unsigned.

uctypes.VOID: Incomplete: VOID is an alias for UINT8, and is provided to conveniently define C’s void pointers: (uctypes.PTR, uctypes.VOID).