Skip to content

Latest commit

 

History

History
163 lines (116 loc) · 7.94 KB

README.md

File metadata and controls

163 lines (116 loc) · 7.94 KB
Raw
title
Quick Start with MaixCDK

Introduction to MaixCDK

MaixCDK provides C++ APIs for commonly used AI functions related to image processing, vision, audio, and peripherals, enabling quick prototyping and stable product development.

MaixCDK is not only a C++ SDK but also auto-generates Python API bindings, so development can be done in Python through MaixPy.

Basic Linux knowledge and a fundamental understanding of cross-compilation are required to use MaixCDK.

How to Find Resources and Troubleshoot

  1. Read MaixCDK source code.
  2. Since MaixCDK shares the same functionality/API as MaixPy, detailed tutorials are not provided separately. Refer to the MaixPy documentation; the principles and code are nearly identical, requiring only minor modifications.
  3. It’s recommended to get hands-on experience with MaixPy before using MaixCDK for a smoother learning curve.
  4. Carefully review the official documentation, including MaixCDK, MaixPy, and hardware documentation.
  5. If issues arise, start by checking MaixCDK FAQ, MaixPy FAQ, MaixCAM Hardware FAQ, and the source code issues.
  6. Check out the MaixHub Share Plaza for community insights.
  7. Read error logs carefully and patiently, following logs from top to bottom, as errors might appear in the middle—don’t skip ahead hastily!

Quick Start

Setting Up the System and Environment

Two options are available:

Local Machine:

Only supported on Linux, with Ubuntu >= 20.04 recommended. Note that the MaixCAM toolchain only supports x86_64 CPUs and is not compatible with ARM-based computers, such as ARM MacOS.

sudo apt update
sudo apt install git cmake build-essential python3 python3-pip
cmake --version # cmake version should be >= 3.13

To compile for a Linux PC (instead of cross-compiling for a dev board), if you’re using Ubuntu, ensure the system version is >=20.04, or some dependencies may be too outdated to compile. Install dependencies following the commands in the Dockerfile. If compilation errors occur, consider using Docker to compile.

Docker:

The Docker environment includes ubuntu20.04 and dependencies, making it ready for compilation. For users familiar with Docker or those facing issues with local setup, refer to the Docker Usage Guide.

Obtaining the Source Code

git clone https://github.com/Sipeed/MaixCDK
  • Stable Release versions can be downloaded from the release page.
  • Alternatively, check MaixPy release assets for maixcdk_version_xxxxx.txt, where xxxxx indicates the MaixPy version in use. Use git checkout xxxx to switch to the corresponding version.

For users in China experiencing slow clone speeds, use git clone https://gitee.com/Sipeed/MaixCDK.

Installing Dependencies

cd MaixCDK
pip install -U pip                     # Update pip to the latest version
pip install -U -r requirements.txt     # Install dependencies

Users in China can add the parameter -i https://pypi.tuna.tsinghua.edu.cn/simple to use the Tsinghua mirror. Dependencies are already installed in the Docker environment, but you can update them to the latest version within the Docker container.

Run maixtool and maixcdk commands in the terminal to view help information.

If the commands are not found, try restarting the terminal or use find / -name "maixtool" to locate maixtool, then set it in the system path using export PATH=directory_containing_maixtool:$PATH.

Compilation

cd examples/hello_world
maixcdk menuconfig

Follow the prompts to select the device platform. A menu appears to configure parameters. For first-time use, the default parameters are fine (or skip menuconfig and go straight to build), then press ESC, and Y to save and exit.

maixcdk build

On first run, this step downloads the necessary toolchain. If downloads are slow, manually download to the specified directory, then run the build again.

Downloaded resources are mainly from GitHub. Set up a proxy for faster downloads. Users in China can download from the main page QQ group file section. To set a proxy: export http_proxy=http://127.0.0.1:8123 https_proxy=http://127.0.0.1:8123, where http://127.0.0.1:8123 is your proxy address.

After compilation, the binary files can be found in the build directory, with dependencies in build/dl_lib.

After code changes, rerun maixcdk build to recompile.

The maixcdk build command scans all file changes before building. If no source files are added or removed, use maixcdk build --no-gen for faster compilation.

Since it uses cmake, the build command always executes cmake first. Adding --no-gen skips cmake and runs make directly, saving time if files haven’t changed.

Run maixcdk distclean to clear all temporary build files and start fresh (this increases build time and is typically used to troubleshoot issues).

Uploading to the Device

Copy the executable and dl_lib folder to the device for execution.

Use scp to copy files, for example:

scp -r dist/ [email protected]:/root/

The default password is root.

Running the Program

Run the program via SSH. Ensure no other programs are running (including the startup application launcher). Steps:

  • Connect MaixVision to the device to close the Launcher, or use SSH to kill the launcher_daemon.
  • SSH into the device, e.g., ssh [email protected], password root.
  • Navigate to the executable directory and run it, e.g., cd /root/dist/camera_display_release && ./camera_display.

Packaging for Release

In the project directory, use maixcdk -p maixcam release to create a program package for maixcam in the dist folder. This package can be uploaded to the MaixHub App Store.

Usage:

  • Method 1: Unzip and copy to the device, run chmod +x program_name && ./program_name.
  • Method 2: Use the App Store application on the device to install from MaixHub.
  • Method 3: For developers, if the device is connected to the same LAN as the PC, use maixcdk deploy to generate a QR code, which the device can scan to install.
  • Method 4: Copy the package to the device and install it by running /maixapp/apps/app_store/app_store install xxx.zip.

Application releases should follow the App Development Guidelines.

Creating a New Project

To create a project:

maixcdk new

Development convention

To get started with MaixCDK, please begin by reading the MaixCDK Development Guidelines.

Adding an API to MaixPy

Since MaixPy’s core is largely MaixCDK, adding APIs to MaixPy is straightforward. Just annotate the function with @maixpy maix.xxx.xxxx.

For example, to implement the following API:

from maix import example

result = example.hello("Bob")
print(result)

Simply add a declaration in maix_api_example.hpp:

namespace maix::example
{
    /**
     * @brief say hello to someone
     * @param[in] name name of someone, string type
     * @return string type, content is hello + name
     * @maixpy maix.example.hello
     */
    std::string hello(std::string name);
}

Then compile the MaixPy project to get an installation package, which can be installed on the device to use the new API—simple, right?

For more detailed documentation, refer to Add API.