MaixCAM MaixPy Pinmap Usage Introduction

Update history
Date Version Author Update content
2025-08-08 1.1.0 Neucrack Refactored the document for better understanding by beginners
2024-06-11 1.0.0 iawak9lkm Initial version of the document

What is a Pin

A pin is a physical hardware pin exposed from the chip/development board. They are visible and tangible around the chip package. In English, we refer to them as Pin.

What is an On-chip Peripheral

These are components built into the chip, other than the CPU cores. The “external” here is relative to the CPU core (internal), as opposed to “off-chip modules” which are external to the entire chip.
For example, the following is the internal architecture diagram of the MaixCAM/MaixCAM-Pro chip:

We can see that the core consists of two RISC-V cores and one 8051 core. In addition, there are many peripherals such as GPIO, UART, and H.264 codec, all of which are considered on-chip peripherals.
Importantly, peripherals here do not necessarily require pins to be brought out of the chip — for example, the H.264 codec is also a peripheral but does not need external pins for interaction.

Also note that here GPIO is a peripheral function within the chip and is not the same as the physical pins (Pin) exposed from the chip.

What is Pin Multiplexing / Pin Mapping

For peripherals that require interaction with the outside world, such as GPIO or I2C,

  • GPIO can control pin input/output,
  • I2C can communicate with other chips via two pins (SDA/SCL).

The simplest design is one pin for each function: for example, in the architecture diagram above, GPIO has 54 pins, and I2C has 5 sets, requiring a total of 54 + 2 × 5 = 64 pins.

The more functions that require pins, the more pins need to be exposed from the chip, which increases chip size. In reality, it’s rare to need all 54 GPIOs and all 5 I2Cs simultaneously.
We can add a pin multiplexing circuit between peripherals and pins, so a single pin can switch between GPIO and I2C. This way, fewer pins can support more functions.
For example, with 50 pins, 10 of them could be configured either as GPIO or as I2C. This is pin multiplexing, usually called pinmux in English.

Due to hardware design limits, most chips allow a pin to be mapped to only a few fixed functions. For example, the MaixCAM-Pro pin mapping is shown below:

maixcam\_pro\_io

Take the A17 pin on the right: it supports three functions — GPIOA17 / UART0_RX / PWM5. We can select which function to use.
If the default is UART0_RX but we need PWM5, we configure the pinmux accordingly.

In MaixPy, the maix.peripheral.pinmap module (or simply maix.pinmap) is used to query and set pin multiplexing (pin function mapping).

Other benefits of pin multiplexing:

  • Save pin count: SoCs integrate many modules (CPU, GPU, memory controllers, I/O interfaces, communication modules, etc.). Assigning separate pins to each function would require huge pin counts, increasing packaging complexity and cost. Pinmux allows one pin to serve multiple purposes, reducing pin numbers significantly.
  • Reduce packaging & manufacturing cost: Fewer pins allow for smaller chip packages, lowering material and manufacturing costs. Smaller packages also save PCB space, enabling more compact designs.
  • Increase design flexibility: Pinmux provides flexibility for different application scenarios by enabling different pin functions via software configuration.
  • Simplify PCB layout: Fewer pins make PCB routing easier, reducing layers and vias, which lowers production difficulty and cost.
  • Optimize performance: Choosing optimal pin functions can shorten signal paths and reduce noise/interference, improving overall system reliability.

Using Pinmap in MaixPy

Pin Function Diagrams

Different boards expose different pins. Below are pin mapping diagrams for each device. For detailed mappings, refer to the schematic or the chip manual’s Pinmux section:

Device Model Pin Diagram Description Full Schematic & Datasheet
MaixCAM Silkscreen like A19 is the pin name; GPIOA19/PWM7 is the function name See Hardware Docs
MaixCAM-Pro maixcam\_pro\_io First name like A19 is the pin name; GPIOA19/PWM7 is the function name See Hardware Docs
MaixCAM2 maixcam2\_io First name like IO0_A2 is the pin name; GPIO0_A2/SPI1_CS0 is the function name See Hardware Docs

Mapping Pin Functions in MaixPy

In MaixPy, use maix.pinmap.set_pin_function to set a pin function.

Example — set A17 pin on MaixCAM/MaixCAM-Pro:

from maix import pinmap

pinmap.set_pin_function("A17", "GPIOA17")

Here A17 is the pin name, and GPIOA17 is the on-chip peripheral function.
This changes the default UART0_RX to GPIO. Now, even if data is sent to UART0, the chip won’t receive it because the pin is in GPIO mode.

After setting to GPIO, follow the GPIO usage docs to output high/low levels or read input.

Get All Functions of a Pin

from maix import pinmap

funcs = pinmap.get_pin_functions("A17")
print(funcs)

Print all pins and their functions:

from maix.peripheral import pinmap

print("All pins of MaixCAM:")
print(pinmap.get_pins())

print("All pin's functions:")
for pin in pinmap.get_pins():
    funcs = pinmap.get_pin_functions(pin)
    print(f"{pin:10s}: {', '.join(funcs)}")

Query Current Function of a Pin

Note: support varies by board type:

  • MaixCAM / MaixCAM-Pro: Mapping info is stored in an array, not read directly from hardware, so you must set it first for accuracy (source code here).
  • MaixCAM2: Reads directly from hardware, so results are accurate.
from maix import pinmap

func = pinmap.get_pin_function("A17")
print(func)

More Examples

See more in MaixPy Examples.

API Documentation

See the detailed Pinmap API Docs.

Default Pin Functions & Notes

Device Model Pin Diagram Default Function Pins to Note
MaixCAM Refer to MaixCAM-Pro 1. UART0 is system log + default serial port
WiFi (SDIO1 + A26)
2. A14 is system status LED; after setting to GPIO, it can be used as normal output
3. User button already has a system key driver; not recommended to read via GPIO
4. IO is 3.3V — do not connect 5V directly
MaixCAM-Pro maixcam\_pro\_io 1. Refer to silkscreen, e.g. 29 = GPIO, RX = UART
2. 6pin defaults to UART and I2C
1. Same as MaixCAM
2. B3 drives a lighting LED, active high
MaixCAM2 maixcam2\_io 1. Refer to silkscreen, e.g. A4 = GPIO, U2R = UART
2. 6pin defaults to UART and I2C
1. IO1_A25 drives a lighting LED, active high
2. IO0_A6 drives system status LED; can be used as GPIO output after init
3. IO is 3.3V — do not connect 5V directly