MaixPy v4: Python on edge AI hardware with camera, display and NPU in ten lines

The maix namespace is the whole interface

MaixPy v4 describes itself as a way to create AI projects with Python on an edge device, and the API design is visible in a single import line. The camera, the display, the image type and the neural network classifier all come from one package:

from maix import camera, display, image, nn

The example that follows is the whole of an image classification application, and the project claims it is an AI vision project within ten lines of code:

classifier = nn.Classifier(model="/root/models/mobilenetv2.mud")
cam = camera.Camera(classifier.input_width(), classifier.input_height(), classifier.input_format())
disp = display.Display()

while 1:
    img = cam.read()
    res = classifier.classify(img)
    max_idx, max_prob = res[0]
    msg = f"{max_prob:5.2f}: {classifier.labels[max_idx]}"
    img.draw_string(10, 10, msg, image.COLOR_RED)
    disp.show(img)

Two details carry most of the design. The camera is constructed with the model's own input width, height and format, so the capture pipeline is configured from the network rather than the other way round, and the network is configured from a .mud file on the device. And the classifier returns a list whose first element is the top result as an index and probability pair, with the label text living on the classifier object as a separate list, which keeps the result payload small enough to be cheap to move around on a microcontroller.

The device is closed over in the loop with no exit condition, because on a board with a fixed screen the loop is the program.

Peripherals are reached the same way as vision

The hardware peripheral story is presented with a serial port example, and it uses the same import shape:

from maix import uart

devices = uart.list_devices()

serial = uart.UART(devices[0], 115200)
serial.write_str("hello world")
print("received:", serial.read(timeout = 2000))

The pattern is a device enumeration followed by a constructor with a port and a baud rate, then a write and a read with a timeout in milliseconds. Nothing here is unique to the serial port; it is the same shape the camera and display follow, which is what makes the API learnable across peripherals.

The repository layout backs up the breadth claim, with example directories for audio, basic use, external devices, gui, mllm, network, peripheral, protocol, tools and vision, plus a hello_maix.py entry point and separate maixpy_v1 examples for the previous generation. The feature overview lists integrated hardware peripheral operations, video streaming, AI vision algorithms, audio algorithms, and LLM and VLM support as things the runtime covers.

The presence of an mllm example directory is worth noting for what it implies about the runtime's scope. Running a large multimodal model on a board with a gigabyte of memory is a very different exercise from running a classifier, and the examples directory suggests the project treats both as in scope.

MaixVision, MaixHub and the matching C SDK

Three supporting pieces sit around the Python runtime, and each addresses a different part of the product lifecycle.

MaixVision is the workstation software for development, described as a handy tool intended to make development easier and faster. MaixHub is an online platform that provides free online AI training, one click to train a model and deploy it to a MaixCAM, aimed at people who have no AI knowledge and no expensive training equipment. The MaixHub service sits at maixhub.com and is presented as a separate product rather than part of the library.

The third piece matters for teams with an existing C codebase. The project provides a C and C++ SDK with identical APIs, which is the mechanism by which the same application logic can be moved between a Python prototype and a production deployment. The hardware comparison table lists the SDK column as MaixCDK plus MaixPy v4 plus opencv and numpy for MaixCAM, and adds scipy for MaixCAM2, and describes the SDK as either a pure Python package or something you cross compile manually.

That cross compile path is the practical reason the repository carries a setup.py with platform logic, a build_run.sh and a run.sh at the top level, plus compile, components, configs and tools directories. A Python package that targets three platforms from one source tree is a packaging problem, not just a runtime problem.

One source tree, three build targets, two Python versions

The setup.py is where the platform matrix is spelled out, and it is more informative than the feature list. The supported board names are linux, maixcam and maixcam2, and the platform names map each to a wheel target: manylinux2014 for the machine architecture on linux, linux_armv7l for m2dock, linux_riscv64 for maixcam, and manylinux2014_aarch64 for maixcam2. The comment in the file explains the manylinux mapping, pointing at the pypa manylinux project for the cross compilation setup.

The Python versions differ by board, and that is the detail most likely to bite:

python_version = {
    "maixcam": [3, 11],
    "maixcam2": [3, 13]
}

So a MaixCAM build targets Python 3.11 and a MaixCAM2 build targets Python 3.13. Code that relies on a standard library behaviour that changed between those versions, or on a third-party package that has not yet shipped a 3.13 wheel for aarch64, will behave differently on the two boards. The board selection is passed on the command line, since the script scans sys.argv for a board name and then removes it, and it also handles a -p argument separately.

The rest of the build logic reads a version from a file at build/config/python_version.txt, and it exits with an error message if that read fails, so a missing build configuration is a hard stop rather than a silent fallback. Each board also has a matching configuration file at configs/config_platform_<board>.mk, and the script exits if one is missing, which keeps the makefile side and the Python side in step.

What the board comparison actually says about hardware choices

The comparison table in the README is the most useful part of the documentation for a developer deciding whether the software is the problem or the hardware is. It lines up Maix-I K210, MaixCAM and MaixCAM2 across CPU, memory, NPU, encoder, decoder, screen, camera, connectivity, operating system and SDK.

The K210 column is the cautionary one. Its NPU figure is recorded as 0.25Tops at INT8 with a note that the official figure claims 1T, it has no encoder and no decoder, no touchscreen, no WiFi beyond 2.4G, no Bluetooth, no USB and no Ethernet, 6MB of SRAM, and it runs an RTOS with C, C++ and MicroPython. The README states plainly that K210 and v831 are outdated, with limitations in memory, performance and missing NPU operators, and that upgrading to MaixCAM and MaixPy v4 is recommended.

MaixCAM lists a 1GHz RISC-V for Linux, a 700MHz RISC-V for the RTOS and a 25 to 300MHz 8051 for low power, 256MB of DDR3, 1Tops at INT8, and encoding up to 2880x1620 at 30fps in H.264, H.265 or JPEG. MaixCAM2 steps up to a pair of 1.2GHz A53 cores for Linux with a 32bit RISC-V E907 for the real-time side, 1GB or 4GB of LPDDR4, 3.2Tops at INT8, encoding at 3840 by 2160 at 30fps, an 800W camera and an AI ISP. Both newer boards carry WiFi 6 on 2.4G and 5G, BLE 5.4 and USB 2.0, and MaixCAM2 moves Ethernet on board as an FPC convertible to an RJ45 module.

The dual-processor arrangement is the architectural point: a Linux side for the general workload and a real-time side for the parts that need deterministic timing.

Where MaixPy is the wrong choice

The clearest limit is vendor coupling. The maix modules are not a general purpose computer vision package; they are bindings to a specific runtime on a specific family of boards, and the model format, the camera API and the display API are the board's. If your deployment target is a Raspberry Pi, a Jetson or a plain x86 server, this library does not help, and the equivalent work would use the vendor's own stack or a portable one.

There is also a version coupling inside the project itself, since this is MaixPy v4 and there is a separate v1 API, with the examples directory keeping maixpy_v1 examples for the previous generation. Code written against v1 is not automatically portable, and the project is explicit about the generation change in its hardware guidance.

The model path is a practical detail that trips people up. The classifier example loads from /root/models/mobilenetv2.mud, so the model has to be present on the device at that path, and the .mud file is the trained artefact format the runtime expects. Combined with the MaixHub training service, that means your model's training pipeline has to produce something MaixPy can load, which narrows how freely you can swap models in and out.

The licensing needs reading too. The licence field on the repository is classified as a custom licence that GitHub cannot classify, with a LICENSE file to consult, and the README badge for the project points at Apache 2.0, so the two statements should be reconciled against the file itself before you ship anything.

For a team that already runs a mainstream Python stack on Linux hardware, the comparison is straightforward: MaixPy trades portability for a much smaller and more integrated system, where camera, display, inference and peripherals are one API on a device with a few hundred megabytes of RAM. Whether that trade is worth it depends on whether the low-power real-time side and the specific board are part of the requirement.

Editorial conclusion

MaixPy v4 fits a developer who wants to ship a small vision or voice device on a MaixCAM board without writing C, or who needs to prototype the same logic on a desktop and then cross compile it for the board. It does not fit a project that needs a general purpose Linux SBC, a mainstream Python package on PyPI with no board dependency, or a vendor-neutral AI stack, because the maix modules are bound to the Sipeed hardware and runtime. Before adopting it, confirm the board you own is supported by the build, since setup.py targets linux, maixcam and maixcam2 with different Python versions, check the licence file yourself because the licence field on the repository is classified as a custom one, and read the model requirements for any network you intend to run, since the example loads a model path from the device filesystem.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. sipeed/MaixPy on GitHub