ssid: SSID of AP password: password of AP, if no password, leave it empty. wait: wait for got IP or failed or timeout. timeout: connect timeout internal, unit second.
+
+
+
return
+
If success, return err.Err.ERR_NONE, else means failed.
img: input image mean: mean value, a list type, e.g. [0.485, 0.456, 0.406], default is empty list means not normalize. scale: scale value, a list type, e.g. [1/0.229, 1/0.224, 1/0.225], default is empty list means not normalize. fit: fit mode, if the image size of input not equal to model's input, it will auto resize use this fit method, default is image.Fit.FIT_FILL for easy coordinate calculation, but for more accurate result, use image.Fit.FIT_CONTAIN is better.
+
img: input image mean: mean value, a list type, e.g. [0.485, 0.456, 0.406], default is empty list means not normalize. scale: scale value, a list type, e.g. [1/0.229, 1/0.224, 1/0.225], default is empty list means not normalize. fit: fit mode, if the image size of input not equal to model's input, it will auto resize use this fit method, default is image.Fit.FIT_FILL for easy coordinate calculation, but for more accurate result, use image.Fit.FIT_CONTAIN is better. copy_result: If set true, will copy result to a new variable; else will use a internal memory, you can only use it until to the next forward. Default true to avoid problems, you can set it to false manually to make speed faster.
return
@@ -1683,7 +1686,7 @@
forward_image
C++ defination code:
-
tensor::Tensors *forward_image(image::Image &img, std::vector<float> mean = std::vector<float>(), std::vector<float> scale = std::vector<float>(), image::Fit fit = image::Fit::FIT_FILL)
+
tensor::Tensors *forward_image(image::Image &img, std::vector<float> mean = std::vector<float>(), std::vector<float> scale = std::vector<float>(), image::Fit fit = image::Fit::FIT_FILL, bool copy_result = true)
In order to make the development board ready to use out of the box, make it easy for users to use without barriers, enable developers to share their interesting applications, and provide effective channels for receiving feedback and even profits, we have launched a simple application framework, including:
+
+
App Store: Developers can upload and share applications, which users can download and use without needing to develop them. Developers can receive certain cash rewards (from MaixHub or user tips).
+
Pre-installed Apps: The official provides some commonly used applications, such as color block detection, AI object detection tracking, QR code scanning, face recognition, etc., which users can use directly or use as serial module.
+
MaixPy + MaixCDK Software Development Kit: Using MaixPy or MaixCDK, you can quickly develop embedded AI visual and audio applications in Python or C/C++, efficiently realizing your interesting ideas.
+
MaixVision Desktop Development Tool: A brand-new desktop code development tool for quick start, debugging, running, uploading code, installing applications to devices, one-click development, and even support for graphical block-based programming, making it easy for elementary school students to get started.
+
+
Everyone is welcome to pay attention to the App Store and share their applications in the store to build a vibrant community together.
+
Packaging Applications
+
Using MaixPy + MaixVison makes it easy to develop, package, and install applications:
+
+
Develop applications with MaixPy in MaixVision, which can be a single file or a project directory.
+
Connect the device.
+
Click the "Install" button at the bottom-left corner of MaixVision, fill in the basic information of the application in the popup window, where the ID is used to identify the application. A device cannot simultaneously install different applications with the same ID, so the ID should be different from the IDs of applications on MaixHub. The application name can be duplicated. You can also upload an icon.
+
Click "Package Application" to package the application into an installer. If you want to upload it to the MaixHub App Store, you can use this packaged file.
+
Click "Install Application" to install the packaged application on the device.
+
Disconnect from the device, and you will see your application in the device's app selection interface. Simply click on it to run the application.
+
+
+
If you develop with MaixCDK, you can use maixcdk release to package an application. Refer to the MaixCDK documentation for specifics.
+
+
Exiting Applications
+
If you have developed a relatively simple application without a user interface and a back button, you can exit the application by pressing the device's function button (usually labeled as USER, FUNC, or OK) or the back button (if available, MaixCAM does not have this button by default).
+
Basic Guidelines for Application Development
+
+
Since touchscreens are standard, it is recommended to create a simple interface with touch interaction. You can refer to examples for implementation methods.
+
Avoid making interfaces and buttons too small, as MaixCAM default screen is 2.3 inches with 552x368 resolution and high PPI. Make sure fingers can easily tap without making mistakes.
+
Implement a simple serial interaction for the main functionality of each application based on the serial protocol (see example). This way, users can directly use it as a serial module. For instance, in a face detection application, you can output coordinates via serial port when a face is detected.
After powering on, it will automatically enter the application selection interface, where various built-in applications are available in the MaixHub App Store. Here you can find descriptions and instructions for using each corresponding application.
+
The commonly used settings are Settings -> Language, as well as Settings -> WiFi. The App Store application can be used for upgrading and installing applications. Once connected to a WiFi network that has internet access, you can scan and install applications from the MaixHub App Store.
+
Moreover, applications you develop can also be uploaded to the MaixHub App Store to share with others. High-quality and outstanding applications will receive official red envelope rewards, and excellent applications will gain recognition and support from everyone.
+
Whether it's a simple application for collecting sensor data or a complex function application, let's work together to create more interesting things!
For beginners just starting out, you can skip this chapter for now and come back to it after mastering the basics of MaixPy development.
+
The latest MaixPy supports running Linux on the MaixCAM hardware, so the underlying MaixPy development is based on the Linux system. Although Sipeed has done a lot of work for developers with MaixPy, making it possible to enjoy using it without knowledge of the Linux system, there might be situations where some low-level operations are necessary or for the convenience of developers unfamiliar with Linux. In this section, we will cover some basic Linux knowledge.
+
Why Linux System is Needed
+
Specific reasons can be researched individually. Here are a few examples in simplified terms that may not sound too technical but are easy for beginners to understand:
+
+
In microcontrollers, our program is usually a loop, but with Linux, we can run multiple programs simultaneously, each appearing to run independently, where the actual execution is handled by the operating system.
+
With a large community of Linux-based developers, required functionalities and drivers can be easily found without the need to implement them from scratch.
+
Linux offers a rich set of accompanying software tools for convenient development and debugging. Some Linux common tools not mentioned in this tutorial can theoretically be used as well.
+
+
File System
+
What is a file system?
+
+
Similar to a computer's file system, Linux manages hardware disks using a file system, making it easy for us to read and write data to the disk.
+
For students who have learned about microcontrollers but not familiar with file system development, imagine having a Flash or TF card where data can be read and written through APIs even after power loss. However, Flash has read/write limitations, requiring a program to ensure its longevity. A file system is like a mature program that manages the Flash space and read/write operations. By calling the file system's APIs, we can significantly reduce development work and ensure stability and security with proven programs.
+
+
Transferring Files between Computer and Device (Development Board)
+
Since the device has Linux and a file system, how do we send files to it?
+
For MaixPy, we offer MaixVision for file management in future versions. Before that, you can use the following method:
+
Here we mainly discuss transferring files through the network. Other methods can be explored on your own by searching for "transferring files to Linux":
+
+
Ensure the device and computer are connected to the same local network, for example:
+
When the MaixCAM's USB port is connected to the computer, a virtual network card is created which can be seen in the device manager on the computer, and the device's IP can be found in the device's Settings -> Device Information.
+
Alternatively, connect to the same local network on the device through Settings -> WiFi.
+
+
+
Use SCP or SFTP protocols on the computer to transfer files to the device. There are many specific software options and methods, such as:
+
On Windows, you can use WinSCP, FileZilla, or the scp command.
+
On Linux, use FileZilla or the scp command.
+
On Mac, use FileZilla or the scp command.
+
+
+
+
Terminal and Command Line
+
The terminal is a tool for communicating with and operating the Linux system, similar to Windows' cmd or PowerShell.
+
For example, we can enter ssh root@maixcam-xxxx.local in the Terminal tool on a Windows system with PowerShell or on a Linux system. You can find the specific name in the device's Settings->Device Information, which allows us to connect to the device through the terminal (both username and password are root).
+
Then, we can operate the device by entering commands. For instance, the ls command can list the files in the current directory of the device, while cd is used to switch to a different directory (similar to clicking folders in file management on a computer),
+
+
cd / # Switch to the root directory
+ls # Display all files in the current directory (root directory)
+
+
This will display similar content as below:
+
+
bin lib media root tmp
+boot lib64 mnt run usr
+dev linuxrc opt sbin var
+etc lost+found proc sys
+
+
For more command learning, please search for Linux command line usage tutorials on your own. This is just to introduce beginners to basic concepts so that when developers mention them, they can understand what they mean.
There are two methods to begin with. If you are new to this and want to keep things simple, you can try using the pre-installed MaixPy firmware on the TF card that comes with the device. You can consider updating it later.
+
However, since we don't know when the TF card you received was manufactured, it is recommended to update the system.
+
Updating the System Directly
+
Follow the steps in Upgrading and Flashing the System to upgrade to the latest system, which already includes the newest MaixPy firmware.
+
Updating Only the MaixPy Firmware
+
Check the latest version information and release notes in the MaixPy repository release page. It includes details about the MaixPy firmware and the system information corresponding to each version.
+
If you prefer not to update the system (since system changes are usually minimal, you can check if there are any system-related changes in the MaixPy update notes before deciding whether to update the system), you can simply update the MaixPy firmware.
+
+
Set up WiFi in the settings to connect the system to the internet.
+
Click on Update MaixPy in the settings app to proceed with the update.
+
+
+
If you are comfortable using the terminal, you can also update MaixPy by using pip install MaixPy -U in the terminal.
MaixVision is a developer programming tool specifically designed for the Maix ecosystem, supporting MaixPy programming and graphical block programming. It also supports online running, debugging, and real-time image preview, allowing the synchronization of the device display screen for easy debugging and development.
+
It also supports packaging applications and installing them on devices, making it convenient for users to generate and install applications with a single click.
+
Additionally, it integrates some handy development tools, such as file management, threshold editors, QR code generators, and more.
+
Using MaixPy Programming and Online Running
+
By following the steps in the Quick Start, we can easily use MaixPy programming and run programs online.
+
Real-time Image Preview
+
MaixPy provides a display module, which can display images on the screen. When calling the show method of the display module, the image will be sent to MaixVision for display in real-time, for example:
+
+
from maix import display, camera
+
+cam = camera.Camera(640, 480)
+disp = display.Display()
+while 1:
+ disp.show(cam.read())
+
+
Here, we capture an image using the camera, and then display it on the screen using disp.show(), which will also transmit the image to MaixVision for display.
+
By clicking the Pause button in the top right corner, the transmission of the image to MaixVision display will stop.
+
Computing the Histogram of an Image
+
In the previous step, we could see the image in real-time on MaixVision. By selecting a region with the mouse, we can view the histogram of that area below the image. Choosing different color representation methods allows us to see histograms of different color channels. This feature helps us find suitable parameters when working on image processing algorithms.
+
Using Graphical Block Programming
+
Currently in development, stay tuned for updates.
+
Distinguishing Between Device File System and Computer File System
+
An important concept to grasp here is distinguishing between the Computer File System and Device File System:
+
+
Computer File System: This operates on the computer. Opening files or projects in MaixVision accesses files stored on the computer. Any changes are automatically saved to the computer's file system.
+
Device File System: When a program runs, it sends files to the device for execution. Therefore, files accessed within the code are read from the device's file system.
+
+
A common issue arises when a file is saved on the computer at D:\data\a.jpg, and then the file is referenced on the device like img = image.load("D:\data\a.jpg"). This file cannot be found on the device because there is no D:\data\a.jpg file stored there.
+
For specific instructions on transferring computer files to the device, please refer to the following section.
+
Transferring Files to the Device
+
Currently in development. In the meantime, you can use alternative tools:
+
Begin by knowing the device's IP address or device name, which MaixVision can search for, or check in the device's Settings -> System Information, where you might find something similar to maixcam-xxxx.local or 192.168.0.123. The username and password are both root, and the file transfer protocol is SFTP with port number 22.
+
There are various user-friendly software options available for different operating systems:
+
For Windows
+
Use tools like WinSCP or FileZilla to connect to the device via SFTP. Provide the necessary device and account information to establish the connection.
+
For further guidance, perform a quick online search.
+
For Linux
+
Use the scp command in the terminal to transfer files to the device, for example:
Method 2: Use tools like FileZilla to connect to the device, transfer the files to the device, choose the SFTP protocol, fill in the device and account information, and connect.
If you have purchased the official (Sipeed) package with a TF card, typically the system has already been pre-programmed at the factory and can be used directly without further steps.
+
However, to avoid using an outdated version of the pre-programmed system, it is highly recommended to first upgrade to the latest system following the tutorial.
+
How to Confirm if System Upgrade is Needed
+
+
Upon booting up to the main menu, click on Settings, then Device Info to check the system's version number.
+
+
Visit the MaixPy Release History page to review the update logs, which contain information on MaixPy firmware and system image updates. If there are significant updates after your current version, it is advisable to upgrade.
+
+
If the latest system update only includes routine MaixPy firmware updates compared to your current system, you may choose not to upgrade. You can simply update MaixPy separately in Settings under Update MaixPy.
+
+
+
+
Obtaining the Latest System
+
Visit the MaixPy Release page to find the latest system image file, such as maixcam_os_20240401_maixpy_v4.1.0.xz.
The tutorial documentation of MaixPy does not delve into specific Python syntax tutorials because there are already too many excellent Python tutorials available. Here, we only introduce what needs to be learned, provide guidance on directions and paths.
+
Introduction to Python
+
Python is an interpreted, object-oriented, dynamically typed high-level programming language.
+
+
Interpreted: It does not require compilation, runs directly. The advantage is rapid development, while a minor drawback is the slower execution speed due to code interpretation on each run. However, most often, the bottleneck lies in the developer's code rather than the language itself.
+
Object-oriented: It supports object-oriented programming, allowing the definition of classes and objects. Compared to procedural languages, it is easier to organize code. For more details, please search independently.
+
Dynamically typed: Variables do not need to declare types, can be assigned directly, and the type will be automatically determined based on the assignment. This reduces code volume, but can also lead to type errors, requiring the developer's attention.
+
+
In conclusion, for developers unfamiliar with Python, it is very easy to get started as Python offers plenty of ready-to-use libraries, a large developer community, short application development cycles, making it highly worthwhile to learn!
+
Python Environment Setup
+
You can install Python on your computer according to the Python tutorial you are following for learning.
+Alternatively, you can connect to a device via MaixVision on MaixVision and then run the program on the development board.
+
What Python Basics are Needed to Use MaixPy?
+
+
Basic concepts of Python.
+
Basic concepts of object-oriented programming.
+
Basic syntax of Python, including:
+
Tab indentation alignment syntax.
+
Variables, functions, classes, objects, comments, etc.
+
Control statements such as if, for, while, etc.
+
Modules and importing modules.
+
Basic data types such as int, float, str, list, dict, tuple, etc.
+
Difference between bytes and str, and conversion.
+
Exception handling, try-except.
+
Common built-in functions like print, open, len, range, etc.
+
Common built-in modules like os, sys, time, random, math, etc.
+
+
+
+
Mastering the above foundational knowledge will enable you to smoothly program with MaixPy. With the help of subsequent tutorials and examples, if unsure, you can refer to search engines, official documentation, or ask ChatGPT to successfully complete your development tasks.
+
For Developers Experienced in Another Object-Oriented Programming Language
+
If you are already proficient in an object-oriented language like C++/Java/C#, you simply need to quickly review Python syntax before starting to use it.
Alternatively, you can explore individual developers' blogs, such as Wow! It's Python.
+
For Developers with C Language Experience but No Object-Oriented Programming Experience
+
If you only know C and lack understanding of object-oriented concepts, you can start by learning about object-oriented programming concepts before diving into Python. It's relatively quick and you can search for video tutorials for entry-level guidance.
+
After following introductory video tutorials, you can then refer to documentation tutorials such as Runoob Tutorial or the Python Official Tutorial to get started!
+
Once you have acquired the basic knowledge, you can start using MaixPy for programming based on the documentation and examples.
+
For Programming Beginners
+
If you have never dealt with programming before, you will need to start learning Python from scratch. Python is also quite suitable as an introductory language. You can search for video tutorials for specific guidance.
+
After mastering the basic syntax, you will be able to use MaixPy for programming by following examples provided.
MaixPy is based on the Python language and provides a wide range of functionalities and APIs for embedded application development. In addition to this, you can also use other Python packages to extend its functionality.
+
Installing Additional Python Packages
+
+
Please note that not all Python packages are supported. Generally, only pure Python packages are supported, not C extension packages. C extension packages may require you to manually cross-compile them on a computer (which is quite complex and won't be covered here).
+
+
Method 1: Installing Using Python Code
+
You can install the package you need in MaixVision using Python code, for example:
+
+
import os
+os.system("pip install package_name")
+
+
To update a package, you can use:
+
+
import os
+os.system("pip install --upgrade package_name")
+
+
Method 2: Installing Using the Terminal and pip Command
+
Follow the terminal usage method introduced in Linux Basics and use pip install package_name to install the package you need.
This page lists common questions and solutions related to MaixPy. If you encounter any issues, please search for answers here first.
+If you cannot find an answer on this page, you can post your question with detailed steps on the MaixHub Discussion Forum.
+
MaixVision cannot find the device?
+
First, confirm whether the connection method is WiFi or USB cable.
+WiFi:
+
+
Ensure that WiFi is correctly connected and has obtained an IP address. You can view the ip in Settings -> Device Info or Settings -> WiFi.
+
+
USB Cable:
+
+
Ensure that the device is connected to the computer via a Type-C data cable, and the device is powered on and has entered the function selection interface.
+
Ensure that the device driver is installed:
+
On Windows, check if there is a USB virtual network adapter device in Device Manager. If there is an exclamation mark, it means the driver is not installed properly. Follow the instructions in Quick Start to install the driver.
+
On Linux, you can check if there is a usb0 device by running ifconfig or ip addr, or check all USB devices with lsusb. Linux already includes the driver, so if the device is not recognized, check the hardware connection, ensure the device system is up-to-date, and ensure the device has booted up properly.
+
On macOS, follow the same steps as Linux.
+
+
+
Additionally, check the quality of the USB cable and try using a high-quality cable.
+
Additionally, check the quality of the computer's USB port. For example, some small form factor PCs have poor EMI design on their USB ports, and connecting a good quality USB hub may allow the device to work. You can also try a different USB port or a different computer.
+
+
MaixVision camera example shows choppy video
+
The default GC4653 camera has a maximum frame rate of 30 frames per second (FPS). Under normal circumstances, the MaixVision display should not appear choppy to the naked eye. If choppiness occurs, first consider transmission issues:
+
+
Check the network connection quality, such as WiFi.
+
If using a USB connection, check the USB cable quality, computer USB port quality, and try using a different computer, USB port, or USB cable for comparison.
+
+
What is the difference between MaixPy v4 and v1/v3?
+
+
MaixPy v4 uses the Python language and is the culmination of the experiences from v1 and v3, offering better supporting software and ecosystem, more features, simpler usage, and more comprehensive documentation. While the hardware has significant improvements, the pricing is even more affordable compared to the other two versions. Additionally, it provides compatibility with the K210 user experience and API, making it easier for users to migrate quickly from v1 to v4.
+
v1 used the Micropython language and had many limitations, such as limited third-party library support. Additionally, due to the hardware performance limitations of the Maix-I (K210), there was not enough memory, limited AI model support, and lack of hardware acceleration for many codecs.
+
v3 also used the Python language and was based on the Maix-II-Dock (v831) hardware. However, the hardware had limited AI model support, and the Allwinner ecosystem was not open enough, with an incomplete API. This version was only intended for use with the Maix-II-Dock (v831) and will not receive further updates.
+
+
Does MaixPy currently only support MaixCAM, or can it work with other boards using the same chipset?
+
MaixPy currently only supports the MaixCAM series of boards. Other boards using the same chipset, including Sipeed's boards like the LicheeRV-Nano, are not supported. It is strongly recommended not to attempt using MaixPy with other boards, as it may result in device damage (such as smoke or screen burn), for which you will be solely responsible.
+
In the future, Sipeed's Maix series of products will continue to be supported by MaixPy. If you have any needs that cannot be met by MaixCAM, you can post your requirements on the MaixHub Discussion Forum or send an email to support@sipeed.com.
+
Can I use a camera or screen other than the officially bundled ones?
+
It is not recommended to use cameras or screens other than the officially bundled ones, unless you have sufficient software and hardware knowledge and experience. Otherwise, it may result in device damage.
+
The officially bundled accessories have been fine-tuned for both software and hardware, ensuring the best performance and allowing for out-of-the-box usage. Other accessories may have different interfaces, drivers, and software, requiring you to calibrate them yourself, which is an extremely complex process.
+
However, if you are an expert, we welcome you to submit a pull request!
It is recommended to purchase the bundle with a TF card, camera, 2.3-inch touchscreen, case, Type-C data cable, Type-C one-to-two mini board, and 4P serial port socket+cable, which will be convenient for later use and development. The following tutorials assume that you already have these accessories (including the screen).
+
If you did not purchase a TF card, you will need to prepare a TF card reader to flash the system.
+
+
Note that currently only the MaixCAM development board is supported. Other development boards with the same chip are not supported, including Sipeed's development boards with the same chip. Please be careful not to purchase the wrong board, which could result in unnecessary waste of time and money.
+
+
Getting Started
+
Prepare the TF Image Card and Insert it into the Device
+
If the package you purchased includes a TF card, it already contains the factory image. If the TF card was not installed in the device at the factory, you will first need to carefully open the case (be careful not to tear the ribbon cables inside) and then insert the TF card. Additionally, since the firmware from the factory may be outdated, you can follow the instructions on Upgrading and Flashing the System to upgrade the system to the latest version.
+
If you did not purchase a TF card, you need to flash the system onto a self-provided TF card. Please refer to Upgrading and Flashing the System for the flashing method, and then install it on the board.
+
Power On
+
Use a Type-C data cable to connect the MaixCAM device and power it on. Wait for the device to boot up and enter the function selection interface.
+
+
If the screen does not display:
+
+
Please confirm that you purchased the bundled TF card. If you confirm that you have a TF card and it is inserted into the device, you can try updating to the latest system.
+
If you did not purchase the TF card bundle, you need to follow the instructions in Upgrading and Flashing the System to flash the latest system onto the TF card.
+
Also, ensure that the screen and camera cables are not loose. The screen cable can easily come off when opening the case, so be careful.
+
+
Connect to the Network
+
For the first run, you need to connect to the network, as you will need it later to activate the device and use the IDE.
+
+
On the device, click Settings, select WiFi, and click the Scan button to start scanning for nearby WiFi. You can click several times to refresh the list.
+
Find your WiFi hotspot. If you don't have a router, you can use your phone as a hotspot.
+
Enter the password and click the Connect button to connect.
+
Wait for the IP address to be obtained. This may take 10 to 30 seconds. If the interface does not refresh, you can exit the WiFi function and re-enter to check, or you can also see the IP information in Settings -> Device Info.
+
+
Update the Runtime Libraries
+
This step is very important!!! If this step is not done properly, other applications and functions may not work (e.g., they may crash).
+
+
First, ensure that you have completed the previous step of connecting to WiFi and have obtained an IP address to access the internet.
+
On the device, click Settings, and select Install Runtime Libraries.
+
After the installation is complete, you will see that it has been updated to the latest version. Then exit.
+
+
If it shows Request failed or 请求失败 (Request failed), please first check if the network is connected. You need to be able to connect to the internet. If it still doesn't work, please take a photo and contact customer service for assistance.
+
Use Built-in Applications
+
Many applications are built-in, such as Find Blobs, AI Detector, Line Follower, etc. For example, Find Blobs:
+
+
Please explore other applications on your own. More applications will be updated in the future. For usage documentation and application updates, please see the MaixHub App Store.
+
Note: The applications only include a part of the functionality that MaixPy can achieve. Using MaixPy, you can create even more features.
+
Use as a Serial Module
+
+
If you want to use the device as the main controller (or if you don't understand what a serial module is), you can skip this step.
+
+
The built-in applications can be used directly as serial modules, such as Find Blobs, Find Faces, Find QR Codes, etc.
+
Usage:
+
+
Hardware connection: You can connect the device to the Type-C one-to-two mini board, which allows you to connect the device via serial to your main controller, such as Arduino, Raspberry Pi, STM32, etc.
+
Open the application you want to use, such as QR code recognition. When the device scans a QR code, it will send the result to your main controller via serial.
+
+
+
The serial baud rate is 115200, the data format is 8N1, and the protocol follows the Maix Serial Communication Protocol Standard. You can find the corresponding application introduction on the MaixHub APP to view the protocol.
+
+
Prepare to Connect the Computer and Device
+
To allow the computer (PC) and the device (MaixCAM) to communicate later, we need to have them on the same local area network. Two methods are provided:
+
+
Method 1 (strongly recommended): Wireless connection. The device uses WiFi to connect to the same router or WiFi hotspot as the computer. You can connect to your WiFi in the device's Settings -> WiFi Settings.
+
Method 2: Wired connection. The device connects to the computer via a USB cable, and the device will act as a virtual USB network card, allowing it to be on the same local area network as the computer via USB.
+
+
+
Method 2 may encounter some problems due to the need for USB and drivers, so it is recommended to start with WiFi instead. You can find common issues in the FAQ.
+
+
+Method 2 has different setup methods on different computer systems, click to expand
+
+
Linux: No additional setup is required. Just plug in the USB cable. Use ifconfig or ip addr to view the usb0 network card. Note that the IP address you see here, e.g., 10.131.167.100, is the computer's IP. The device's IP is the last octet changed to 1, i.e., 10.131.167.1.
+
Windows: You can first confirm if a RNDIS device has been added in the Network Adapters. If so, you can use it directly. Otherwise, you need to manually install the RNDIS network card driver:
+
Open the computer's Device Manager.
+
Then find a RNDIS device with a question mark under Other Devices, right-click and select Update Driver Software.
+
Select Browse my computer for driver software.
+
Select Let me pick from a list of available drivers on my computer.
+
Select Network Adapters, then click Next.
+
On the left, select Microsoft, on the right, select Remote NDIS Compatible Device, then click Next, and select Yes.
+
After installation, the effect is as follows:
+
+
+
+
MacOS: No additional setup is required. Just plug in the USB cable. Use ifconfig or ip addr to view the usb0 network card. Note that the IP address you see here, e.g., 10.131.167.100, is the computer's IP. The device's IP is the last octet changed to 1, i.e., 10.131.167.1.
Connect the device and computer with a Type-C cable, open MaixVision, and click the "Connect" button in the bottom left corner. It will automatically search for devices. After a short wait, you will see the device, and you can click the connect button next to it to connect to the device.
+
+
If no device is detected, you can also manually enter the device's IP address in the device's Settings -> Device Info. You can also find solutions in the FAQ.
+
After a successful connection, the function selection interface on the device will disappear, and the screen will turn black, releasing all hardware resources. If there is still an image displayed, you can disconnect and reconnect.
+
Here is a video example of using MaixVision:
+
+
Run Examples
+
Click Example Code on the left side of MaixVision, select an example, and click the Run button in the bottom left to send the code to the device for execution.
+
For example:
+
+
hello_maix.py: Click the Run button, and you will see messages printed from the device in the MaixVision terminal, as well as an image in the upper right corner.
+
camera_display.py: This example will open the camera and display the camera view on the screen.
+
+
+
from maix import camera, display, app
+
+disp = display.Display() # Construct a display object and initialize the screen
+cam = camera.Camera(640, 480) # Construct a camera object, manually set the resolution to 640x480, and initialize the camera
+while not app.need_exit(): # Keep looping until the program exits (you can exit by pressing the function key on the device or clicking the stop button in MaixVision)
+ img = cam.read() # Read the camera view and save it to the variable img, you can print(img) to print the details of img
+ disp.show(img) # Display img on the screen
+
+
+
yolov5.py will detect objects in the camera view, draw bounding boxes around them, and display them on the screen. It supports detection of 80 object types. For more details, please see YOLOv5 Object Detection.
+
+
You can try other examples on your own.
+
+
If you encounter image display stuttering when using the camera examples, it may be due to poor network connectivity, or the quality of the USB cable or the host's USB being too poor. You can try changing the connection method or replacing the cable, host USB port, or computer.
+
+
Install Applications on the Device
+
The above examples run code on the device, but the code will stop running when MaixVision is disconnected. If you want the code to appear in the boot menu, you can package it as an application and install it on the device.
+
Click the Install App button in the bottom left corner of MaixVision, fill in the application information, and the application will be installed on the device. Then you will be able to see the application on the device.
+ You can also choose to package the application and share your application to the MaixHub App Store.
+
+
The default examples do not explicitly write an exit function, so you can exit the application by pressing the function key on the device. (For MaixCAM, it is the user key.)
+
+
If you want the program to start automatically on boot, you can set it in Settings -> Boot Startup.
+
Next Steps
+
If you like what you've seen so far, please be sure to give the MaixPy open-source project a star on GitHub (you need to log in to GitHub first). Your star and recognition is the motivation for us to continue maintaining and adding new features!
+
Up to this point, you've experienced the usage and development workflow. Next, you can learn about MaixPy syntax and related features. Please follow the left sidebar to learn. If you have any questions about using the API, you can look it up in the API documentation.
+
It's best to learn with a specific purpose in mind, such as working on an interesting small project. This way, the learning effect will be better. You can share your projects and experiences on the MaixHub Share Plaza and receive cash rewards!
+
Share and Discuss
+
+
MaixHub Project and Experience Sharing: Share your projects and experiences, and receive cash rewards. The basic requirements for receiving official rewards are:
+
Reproducible: A relatively complete process for reproducing the project.
+
Showcase: No detailed project reproduction process, but an attractive project demonstration.
+
Bug-solving experience: Sharing the process and specific solution for resolving a particular issue.
Sometimes we need to execute a function efficiently, and the speed of Python cannot meet the requirements. In such cases, we can use C/C++ or other compiled languages to implement the function.
+
General Function Encapsulation
+
If the function you want to encapsulate does not depend on other functionalities of MaixPy, you can directly use the general method of adding C/C++ modules with Python, such as ffi, ctype, etc. You can search for relevant methods online.
+
+
Welcome to contribute methods via PR
+
+
If Your Module Needs to Depend on Other Basic APIs of MaixPy
+
You need to learn how to compile and use MaixCDK first, because MaixPy is generated from MaixCDK APIs. Some functionalities in MaixPy are also available in MaixCDK, and then... TODO
maixcam Can be replaced with other board config, see setup.py 's platform_names variable.
+
After build success, you will find wheel file in dist directory, use pip install -U MaixPy****.wheel on your device to install or upgrade.
+
+
python setup.py bdist_wheel maixcam --skip-build will not execute build command and only pack wheel, so you can use maixcdk menuconfig and maixcdk build first to customize building.
+
+
Build manually
+
+
maixcdk build
+
+
Run test after modify source code
+
+
First, build source code by
+
+
+
maixcdk build
+
+
+
If build for PC self(platform linux):
+
+
Then execute ./run.sh your_test_file_name.py to run python script.
+
+
cd test
+./run.sh examples/hello_maix.py
+
+
+
If cross compile for borad:
+
The fastest way is copy maix dir to device's /usr/lib/python3.11/site-packages/ directory, then run script on device.
+
Or pack wheel and install on device by pip install -U MaixPy****.wheel, then run script on device.
+
+
+
+
Preview documentation locally
+
Documentation in docs directory, use Markdown format, you can use teedoc to generate web version documentation.
+
And the API doc is generated when build MaixPy firmware, if you don't build MaixPy, the API doc will be empty.
Click the "Edit this page" button in the top right corner of the documentation you want to modify to enter the GitHub source documentation page.
+
Make sure you are logged in to your GitHub account.
+
Click the pencil icon in the top right corner of the GitHub preview documentation page to modify the content.
+
GitHub will prompt you to fork a copy to your own repository. Click the "Fork" button.
+
+
+
This step forks the MaixPy source code repository to your own account, allowing you to freely modify it.
+
+
+
Modify the documentation content, then fill in the modification description at the bottom of the page, and click "Commit changes".
+
Then find the "Pull requests" button in your repository and click to create a new Pull request.
+
In the pop-up page, fill in the modification description and click "Submit Pull request". Others and administrators can then see your modifications on the Pull requests page.
+
Wait for the administrator to review and approve, and your modifications will be merged into the MaixPy source code repository.
+
After the merge is successful, the documentation will be automatically updated to the MaixPy official documentation.
+
+
+
Due to CDN caching, it may take some time to see the update. For urgent updates, you can contact the administrator for manual refreshing.
+You can also visit en.wiki.sipeed.com/maixpy to view the GitHub Pages service version, which is updated in real-time without caching.
Before modifying the code, it is best to create an issue first, describing the content you want to modify to let others know your ideas and plans, so that everyone can participate in the modification discussion and avoid duplication of effort.
+
Click the "Fork" button in the top right corner to fork a copy of the MaixPy code repository to your own account.
+
Then clone a copy of the code from your account to your local machine.
+
After modifying the code, commit it to your repository.
+
Then find the "Pull requests" button in your repository and click to create a new Pull request.
+
In the pop-up page, fill in the modification description and click "Submit Pull request". Others and administrators can then see your modifications on the Pull requests page.
+
Wait for the administrator to review and approve, and your modifications will be merged into the MaixPy source code repository.
+
+
+
Note that most of the MaixPy code is automatically generated from MaixCDK, so if you modify the C/C++ source code, you may need to modify this repository first.
subprocess.CalledProcessError: Command '('lsb_release', '-a')' returned non-zero exit status 1.
+
Edit /usr/bin/lsb_release as root, change the first line from #!/usr/bin/python3 to python3.
+
Then compile again and it should work.
+
ImportError: arg(): could not convert default argument 'format: maix::image::Format' in method '<class 'maix._maix.camera.Camera'>.init' into a Python object (type not registered yet?)
+
Pybind11 need you to register image::Format first, then you can use it in camera::Camera, to we must fist define image::Format in generated build/maixpy_wrapper.cpp source file.
+
To achieve this, edit components/maix/headers_priority.txt, the depended on should be placed before the one use it.
+e.g.
In addition to developing with MaixPy, there is also a corresponding C/C++ SDK available, called MaixCDK.
+
Introduction to MaixCDK
+
MaixPy is built on top of MaixCDK, and most of MaixPy's APIs are automatically generated based on MaixCDK's APIs. Therefore, any functionality available in MaixPy is also included in MaixCDK.
+If you are more familiar with C/C++ programming or require higher performance, you can use MaixCDK for development.
+
Using MaixCDK
+
The MaixCDK code repository is located at github.com/sipeed/MaixCDK, where you can find the MaixCDK code and documentation.
Sometimes it is necessary to send images to a server or push video from a camera to a server. Here, we provide the simplest method, which is to compress images into JPEG format and send them one by one to the server.
+
Note, this is a very basic method and not a formal way to stream video. It is also not suitable for high-resolution, high-frame-rate video streams, as it involves sending images one by one. For more efficient video streaming, please use the RTSP or RTMP modules discussed later.
+
How to Use
+
+
from maix import image
+import requests
+
+# create image
+img = image.Image(640, 480, image.Format.FMT_RGB)
+# draw something
+img.draw_rect(60, 60, 80, 80, image.Color.from_rgb(255, 0, 0))
+
+# convert to jpeg
+jpeg = img.to_format(image.Format.FMT_JPEG) # image.Format.FMT_PNG
+# get jpeg bytes
+jpeg_bytes = jpeg.to_bytes()
+
+# faster way, borrow memory from jpeg object,
+# but be careful, when jpeg object is deleted, jpeg_bytes object MUST NOT be used, or program will crash
+# jpeg_bytes = jpeg.to_bytes(copy = False)
+
+# send image binary bytes to server
+url = "http://192.168.0.123:8080/upload"
+res = requests.post(url, data=jpeg_bytes)
+print(res.status_code)
+print(res.text)
+
+
As you can see, the image is first converted into JPEG format, and then the binary data of the JPEG image is sent to the server via TCP.
Then, the visual AI we use is generally based on the deep neural network learning method. If you are interested, you can check out Deep Neural Network (DNN) Basics.
+
Using Visual AI in MaixPy
+
Using visual AI in MaixPy is very simple. By default, commonly used AI models are provided, and you can use them directly without having to train the models yourself. You can find the maixcam models in the MaixHub Model Library.
+
Additionally, the underlying APIs have been well-encapsulated, and you only need to make simple calls to implement them.
+
If you want to train your own model, you can start with MaixHub Online Training. On the online platform, you can train models just by clicking, without the need to purchase expensive machines, set up complex development environments, or write code, making it very suitable for beginners and also for experienced users who are too lazy to read code.
+
Generally, once you have obtained the model file, you can transfer it to the device and call the MaixPy API to use it. The specific calling methods are discussed in the following sections.
img is the camera image obtained through cam.read()
+
img.resize(160, 120) is used to scale down the image to a smaller size, allowing the algorithm to compute faster with a smaller image
+
new_img.find_apriltags(families = families) is used to find Apriltag labels, and the query results are saved in apriltags for further processing. The families parameter is used to select the Apriltag family, defaulting to image.ApriltagFamilies.TAG36H11
+
+
+
Process the recognized label results and display them on the screen
+
+
for a in apriltags:
+ # Get position information (and map coordinates to the original image)
+ x = int(a.x() * x_scale)
+ y = int(a.y() * y_scale)
+ w = int(a.w() * x_scale)
+ corners = a.corners()
+ for i in range(4):
+ corners[i][0] = int(corners[i][0] * x_scale)
+ corners[i][1] = int(corners[i][1] * y_scale)
+
+ # Display
+ for i in range(4):
+ img.draw_line(corners[i][0], corners[i][1], corners[(i + 1) % 4][0], corners[(i + 1) % 4][1], image.COLOR_RED)
+ img.draw_string(x + w, y, "id: " + str(a.id()), image.COLOR_RED)
+ img.draw_string(x + w, y + 15, "family: " + str(a.family()), image.COLOR_RED)
+ img.draw_string(x + w, y + 30, "rotation : " + str(180 * a.rotation() // 3.1415), image.COLOR_RED)
+
+
+
Iterate through the members of apriltags, which is the result of scanning Apriltag labels through img.find_apriltags(). If no labels are found, the members of apriltags will be empty.
+
x_scale and y_scale are used to map coordinates. Since new_img is a scaled-down image, the coordinates of the Apriltag need to be mapped to be drawn correctly on the original image img.
+
a.corners() is used to get the coordinates of the four vertices of the detected label, and img.draw_line() uses these four vertex coordinates to draw the shape of the label.
+
img.draw_string is used to display the label content, where a.x() and a.y() are used to get the x and y coordinates of the top-left corner of the label, a.id() is used to get the label ID, a.family() is used to get the label family type, and a.rotation() is used to get the rotation angle of the label.
+
+
+
+
Common Parameter Explanations
+
Here are explanations for common parameters. If you can't find parameters to implement your application, you may need to consider using other algorithms or extending the required functionality based on the current algorithm's results.
+
+
+
+
Parameter
+
Description
+
Example
+
+
+
+
+
roi
+
Set the rectangular region for the algorithm to compute. roi=[x, y, w, h], where x and y represent the coordinates of the top-left corner of the rectangle, and w and h represent the width and height of the rectangle. The default is the entire image.
+
Compute the region with coordinates (50,50) and a width and height of 100: img.find_apriltags(roi=[50, 50, 100, 100])
+
+
+
families
+
Apriltag label family type
+
Scan for labels from the TAG36H11 family: img.find_apriltags(families = image.ApriltagFamilies.TAG36H11)
+
+
+
+
This article introduces common methods. For more API information, please refer to the image section of the API documentation.