diff --git a/.github/workflows/build_maixcam.yml b/.github/workflows/build_maixcam.yml index e0f3fc75..3eacf39b 100755 --- a/.github/workflows/build_maixcam.yml +++ b/.github/workflows/build_maixcam.yml @@ -60,8 +60,6 @@ jobs: echo "----------------------------------" echo "-- Build MaixPy for MaixCAM now --" echo "----------------------------------" - maixcdk distclean - maixcdk build -p maixcam --verbose python setup.py bdist_wheel maixcam # Runs a set of commands using the runners shell @@ -81,13 +79,15 @@ jobs: echo "== checkout gh-pages branch ==" cd out cp -r ../../.github . + git config --global init.defaultBranch gh-pages git init - git config user.name ${user_name} + git config user.name "${user_name}" git config user.email ${user_email} remote_addr="https://Neutree:${{ secrets.GITHUB_TOKEN }}@${remote_addr}" echo "-- user ${user_name}" echo "-- remote addr: ${remote_addr}" git remote add origin "${remote_addr}" + echo "== add web files ==" git add -A git commit -m "Rebuild MaixPy doc by commit $GITHUB_REF" git push origin HEAD:gh-pages --force diff --git a/.github/workflows/trigger_wiki.yml b/.github/workflows/trigger_wiki.yml index 76e9af21..75f13bb8 100755 --- a/.github/workflows/trigger_wiki.yml +++ b/.github/workflows/trigger_wiki.yml @@ -4,11 +4,10 @@ name: trigger wiki # Controls when the action will run. on: - # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ gh-pages ] - # pull_request: - # branches: [ main ] + pull_request: + branches: [ gh-pages ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: @@ -16,9 +15,10 @@ on: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" - build: + trigger_wiki: + name: trigger sipeed_wiki # Only run job for specific repository - if: github.repository == 'sipeed/MaixPy' + # if: github.repository == 'sipeed/MaixPy' # The type of runner that the job will run on runs-on: ubuntu-latest # strategy: @@ -27,7 +27,8 @@ jobs: # Steps represent a sequence of tasks that will be executed as part of the job steps: - - uses: actions/github-script@v6 + - name: trigger sipeed wiki request + uses: actions/github-script@v6 with: github-token: ${{ secrets.DISPATCH_PAT }} script: | diff --git a/docs/doc/assets/maixvision_browser.jpg b/docs/doc/assets/maixvision_browser.jpg new file mode 100644 index 00000000..3bcda9b9 Binary files /dev/null and b/docs/doc/assets/maixvision_browser.jpg differ diff --git a/docs/doc/assets/maixvision_browser2.jpg b/docs/doc/assets/maixvision_browser2.jpg new file mode 100644 index 00000000..94c2895c Binary files /dev/null and b/docs/doc/assets/maixvision_browser2.jpg differ diff --git a/docs/doc/en/basic/maixvision.md b/docs/doc/en/basic/maixvision.md index 5d64cfe3..7d67f400 100644 --- a/docs/doc/en/basic/maixvision.md +++ b/docs/doc/en/basic/maixvision.md @@ -1,27 +1,27 @@ --- -title: MaixVision - MaixPy Programming + Graphical Block Programming +title: MaixVision -- MaixPy Programming IDE + Graphical Block Programming --- ## Introduction -[MaixVision](https://wiki.sipeed.com/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. +[MaixVision](https://wiki.sipeed.com/maixvision) is a development tool specifically designed for the Maix ecosystem, supporting MaixPy programming and graphical block programming. It allows for online operation and debugging, real-time image preview, and synchronizing images from device displays, which is convenient for 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. +It also supports packaging and installing applications on devices, allowing users to easily generate and install applications with one click. -Additionally, it integrates some handy development tools, such as file management, threshold editors, QR code generators, and more. +In addition, it integrates several handy tools for development, such as file management, threshold editor, QR code generator, and more. ## Download -Visit [MaixVision home page](https://wiki.sipeed.com/maixvision) to download. +Visit the [MaixVision homepage](https://wiki.sipeed.com/maixvision) to download. + ## Using MaixPy Programming and Online Running -By following the steps in the [Quick Start](../README.md), we can easily use MaixPy programming and run programs online. +Follow the steps in [Quick Start](../README.md) to connect your device, and you can easily use MaixPy programming and run it 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: - +MaixPy provides a `display` module that can show images on the screen. Also, when the `show` method of the `display` module is called, it sends the image to be displayed on MaixVision, for example: ```python from maix import display, camera @@ -31,74 +31,84 @@ 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. +Here we use the camera to capture an image, then display it on the screen using the `disp.show()` method, and also send it to MaixVision for display. -By clicking the `Pause` button in the top right corner, the transmission of the image to MaixVision display will stop. +When we click the 'pause' button in the top right corner, it will stop sending images to MaixVision. -## 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. +## Code Auto Completion -## Using Graphical Block Programming +Code suggestions depend on local Python packages installed on your computer. To enable code suggestions, you need to install Python on your computer and the required Python packages. -Currently in development, stay tuned for updates. +* To install Python, visit the [Python official website](https://python.org/). +* To install the required packages, for MaixPy, for instance, you need to install the MaixPy package on your computer using `pip install MaixPy`. If `MaixPy` gets updated, you should update it on both your computer and device. On your computer, manually execute `pip install MaixPy -U` in the terminal. For device updates, update directly in the `Settings` application. +> Users in China can use a local mirror `pip install -i https://pypi.tuna.tsinghua.edu.cn/simple MaixPy`. +* Restart MaixVision to see the code suggestions. +> If suggestions still do not appear, you can manually set the path to the Python executable in settings and restart. -## Distinguishing Between `Device File System` and `Computer File System` +>! Note that installing Python packages on your computer is just for code suggestions. The actual code runs on the device (development board), and the device must also have the corresponding packages to run properly. -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. +> Additionally, while you have the MaixPy package installed on your computer, due to our limited resources, we cannot guarantee that you can directly use the Maix package in your computer's Python. Please run it on supported devices. -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 +## Calculating the Image Histogram + +In the previous step, we could see the image in real-time in MaixVision. By selecting an area with the mouse, we can view the histogram for that area at the bottom of the screen, displaying different color channels. + +This feature is helpful when finding suitable parameters for some image processing algorithms. -Currently in development. In the meantime, you can use alternative tools: +## Distinguishing Between `Device File System` and `Computer File System` -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`. +Here we have an important concept to grasp: **distinguish between the `Device File System` and the `Computer File System`**. +* **Computer File System**: Operates on the computer. Opening a file or project in MaixVision accesses files on the computer, and saving is automatically done to the computer's file system. +* **Device File System**: The program sends the code to the device for execution, so the files used in the code are read from the device's file system. -There are various user-friendly software options available for different operating systems: +A common issue is when students save a file on the computer, such as `D:\data\a.jpg`, and then use this file on the device with `img = image.load("D:\data\a.jpg")`. Naturally, the file cannot be found because the device does not have `D:\data\a.jpg`. -### For Windows +For specifics on how to send files from the computer to the device, refer to the following section. -Use tools like [WinSCP](https://winscp.net/eng/index.php) or [FileZilla](https://filezilla-project.org/) 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. +## Transferring Files to the Device -### For Linux +First, connect to the device, then click the button to browse the device file system, as shown below. Then you can upload files to the device or download files to the computer. -Use the `scp` command in the terminal to transfer files to the device, for example: +![maixvision_browser2](../../assets/maixvision_browser2.jpg) -```bash -scp /path/to/your/file.py root@maixcam-xxxx.local:/root -``` +![maixvision_browser](../../assets/maixvision_browser.jpg) -### For Mac +.. details:: Alternatively, other tools can be used, click to expand + First, know the device's IP address or name, which MaixVision can find, or see in the device's `Settings->System Information`, such as `maixcam-xxxx.local` or `192.168.0.123`. + The username and password are `root`, using the `SFTP` protocol for file transfer, and the port number is `22`. -- **Method 1**: Use the `scp` command in the terminal to transfer files to the device, for example: + There are many useful tools available for different systems: -```bash -scp /path/to/your/file.py root@maixcam-xxxx.local:/root -``` + ### Windows -* **Method 2**: Use tools like [FileZilla](https://filezilla-project.org/) to connect to the device, transfer the files to the device, choose the `SFTP` protocol, fill in the device and account information, and connect. + Use [WinSCP](https://winscp.net/eng/index.php) or [FileZilla](https://filezilla-project.org/) to connect to the device and transfer files, choosing the `SFTP` protocol and entering the device and account information to connect. + Specific instructions can be searched online. + ### Linux -## Code Completion + In the terminal, use the `scp` command to transfer files to the device, such as: -Code completion depends on the Python packages installed locally on your computer. To enable code completion, you need to install Python on your computer and also the Python packages required for completion. + ```bash + scp /path/to/your/file.py root@maixcam-xxxx.local:/root + ``` -* To install Python, visit the [Python official website](https://python.org/) for installation. -* To install the packages required for completion, for instance, for MaixPy, you need to install the MaixPy package on your computer as well by using `pip install MaixPy`. -* Restart MaixVision to see the code completion. + ### Mac -> If the completion still does not work, you can manually set the path to the python executable in the settings and restart. + * **Method 1**: In the terminal, use the `scp` command to transfer files to the device, such as: + ```bash + scp /path/to/your/file.py root@maixcam-xxxx.local:/root + ``` ->! Note that installing Python packages on your computer is only for code completion purposes. The actual code still runs on the device (development board), and the device must also have the corresponding packages for proper operation. + * **Method 2**: Use [FileZilla](https://filezilla-project.org/) or other tools to connect to the device and transfer files, choosing the `SFTP` protocol and entering the device and account information to connect. + + +## Using Graphical Block Programming -> Additionally, although you have installed the MaixPy package on your computer, due to our limited resources, we do not guarantee that you will be able to directly import the maix package in Python on your computer for use. Please run it on supported devices. +Under development, please stay tuned. diff --git a/docs/doc/en/peripheral/uart.md b/docs/doc/en/peripheral/uart.md index e69de29b..7fe90b42 100644 --- a/docs/doc/en/peripheral/uart.md +++ b/docs/doc/en/peripheral/uart.md @@ -0,0 +1,39 @@ +--- +title: Introduction to MaixPy UART Serial Communication +--- + +## Introduction to Serial Communication + +Serial communication is a method of communication that includes definitions for both hardware and communication protocols. + +* Hardware includes: + * 3 pins: `GND`, `RX`, `TX`. The communication is cross-connected between RX and TX, meaning one side's TX sends to the other side's RX, and both sides' GND are connected together. + * Controllers, generally located inside the chip, are also referred to as UART peripherals. Typically, a chip will have one or more UART controllers, each associated with specific pins. +* Communication protocol: To enable smooth communication between the two parties, a set of protocols has been established. Specific details can be self-studied, with common parameters including baud rate and parity bits, among which baud rate is the most frequently used parameter. + +Using the board's serial port, data communication can be established with other microcontrollers or SoCs. For example, human detection functions can be implemented on MaixCAM, and upon detecting coordinates, the information can be sent to an STM32 microcontroller through the serial port. + +## Using Serial Communication in MaixPy + +By default, MaixCAM routes a serial port from the USB port, which can be directly utilized by connecting a compatible Type-C adapter board. Alternatively, the `A16(TX)` and `A17(RX)` pins on the board can be used without an adapter board, which are equivalent to the pins routed from the USB port. + +When using the USB-routed serial port on MaixCAM, **attention** is required regarding the Type-C orientation. The `RX` and `TX` may swap when the Type-C is flipped, which might result in communication failures. If issues arise, try flipping the Type-C connector to see if the communication restores. This is considered a design flaw, but since frequent unplugging is uncommon, it is generally acceptable. + +Once the two communicating boards are properly connected (cross-connecting RX and TX, with both sides' GND connected together), you can start using the software. + +Using the serial port in MaixPy is straightforward: + +```python +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)) +``` + +This script first lists all serial port devices in the system, then uses the first device, which is the one routed from the Type-C as mentioned above. + +For more information on the UART API, please refer to the [UART API Documentation](../../../api/maix/peripheral/uart.md). + diff --git a/docs/doc/zh/basic/maixvision.md b/docs/doc/zh/basic/maixvision.md index 85789882..b60ffb79 100644 --- a/docs/doc/zh/basic/maixvision.md +++ b/docs/doc/zh/basic/maixvision.md @@ -1,5 +1,5 @@ --- -title: MaixVision -- MaixPy 编程 + 图形化积木编程 +title: MaixVision -- MaixPy 编程 IDE + 图形化积木编程 --- @@ -37,19 +37,30 @@ while 1: 当我们点击了右上角的`暂停`按钮,就会停止发送图像到 MaixVision 显示。 +## 代码自动补全 -## 计算图像的直方图 -在上一步中我们可以在 MaixVision 中实时看到图像,我们用鼠标框选一个区域,图像下方就能看到这个区域的直方图了,选择不同的颜色表示方法,可以看到不同的颜色通道的直方图。 +代码提示依赖电脑本地的 Python 包,为了实现代码提示,我们需要在电脑中安装 Python,并且安装需要提示的 Python 包。 -这个功能方便我们在做某些图像处理算法时找到一些合适的参数。 +* 安装 Python 请访问 [Python 官网](https://python.org/)安装。 +* 安装需要提示的包,比如对于 MaixPy, 你需要在电脑也安装一份 MaixPy 包,在电脑使用`pip install MaixPy`即可安装好,如果`MaixPy`更新了,你也需要在电脑和设备更新到`MaixPy`,电脑手动在终端执行`pip install MaixPy -U`即可,设备更新直接在`设置`应用中更新即可。 +> 中国国内用户可以使用国内镜像`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple MaixPy`。 +* 重启 MaixVision 就能够看到代码提示了。 +> 如果仍然不能提示,可以手动在设置中设置 python 可执行文件的路径后重启。 +>! 注意在电脑安装 Python 包这里只是为了用作代码提示,实际代码运行还是在设备(开发板)上,设备上也要有对应的包才能正常运行。 -## 使用图形化积木编程 -开发中,敬请期待。 +> 另外,虽然你在电脑上安装了 MaixPy 包,但是由于我们精力有限,我们不确保你能直接在电脑的 Python 导入 maix 包进行使用,请在支持的设备上运行。 + +## 计算图像的直方图 + +在上一步中我们可以在 MaixVision 中实时看到图像,我们用鼠标框选一个区域,图像下方就能看到这个区域的直方图了,选择不同的颜色表示方法,可以看到不同的颜色通道的直方图。 + +这个功能方便我们在做某些图像处理算法时找到一些合适的参数。 + ## 区分`设备文件系统`和`电脑文件系统` 这里我们有一个比较重要的概念需要掌握:**分清楚`设备文件系统`和`电脑文件系统`**。 @@ -63,55 +74,44 @@ while 1: ## 传输文件到设备 -开发中,敬请期待。 - -目前可以用其它工具代替: - -先知道设备的 ip 地址或者设备名称,MaixVision 就可以搜索到, 或者在设备`设置->系统信息`中看到,比如类似 `maixcam-xxxx.local` 或者 `192.168.0.123`。 -用户名和密码都是 `root`, 使用 `SFTP` 协议传输文件,端口号是 `22`。 - -然后不同系统下都有很多好用的软件: - -### Windows 下 +先连接设备,然后点击浏览设备文件系统的按钮,有两个入口,如下图,然后就能上传文件到设备,或者从设备下载文件到电脑了。 -使用 [WinSCP](https://winscp.net/eng/index.php) 或者 [FileZilla](https://filezilla-project.org/) 等工具连接设备,将文件传输到设备上,选择 `SFTP` 协议填写设备和账号信息连接即可。 +![maixvision_browser2](../../assets/maixvision_browser2.jpg) -具体不懂的可以自行搜索。 +![maixvision_browser](../../assets/maixvision_browser.jpg) -### Linux 下 -终端使用 `scp` 命令传输文件到设备上,比如: +.. details::也可以用其它工具代替,点击展开 + 先知道设备的 ip 地址或者设备名称,MaixVision 就可以搜索到, 或者在设备`设置->系统信息`中看到,比如类似 `maixcam-xxxx.local` 或者 `192.168.0.123`。 + 用户名和密码都是 `root`, 使用 `SFTP` 协议传输文件,端口号是 `22`。 -```bash -scp /path/to/your/file.py root@maixcam-xxxx.local:/root -``` - -### Mac 下 - -* **方法一**:终端使用 `scp` 命令传输文件到设备上,比如: -```bash -scp /path/to/your/file.py root@maixcam-xxxx.local:/root -``` + 然后不同系统下都有很多好用的软件: -* **方法二**:使用 [FileZilla](https://filezilla-project.org/) 等工具连接设备,将文件传输到设备上,选择 `SFTP` 协议填写设备和账号信息连接即可。 + ### Windows 下 + 使用 [WinSCP](https://winscp.net/eng/index.php) 或者 [FileZilla](https://filezilla-project.org/) 等工具连接设备,将文件传输到设备上,选择 `SFTP` 协议填写设备和账号信息连接即可。 -## 代码提示 + 具体不懂的可以自行搜索。 + ### Linux 下 -代码提示依赖电脑本地的 Python 包,为了实现代码提示,我们需要在电脑中安装 Python,并且安装需要提示的 Python 包。 + 终端使用 `scp` 命令传输文件到设备上,比如: -* 安装 Python 请访问 [Python 官网](https://python.org/)安装。 -* 安装需要提示的包,比如对于 MaixPy, 你需要在电脑也安装一份 MaixPy 包,在电脑使用`pip install MaixPy`即可安装好。 -> 中国国内用户可以使用国内镜像`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple MaixPy`。 -* 重启 MaixVision 就能够看到代码提示了。 -> 如果仍然不能提示,可以手动在设置中设置 python 可执行文件的路径后重启。 + ```bash + scp /path/to/your/file.py root@maixcam-xxxx.local:/root + ``` ->! 注意在电脑安装 Python 包这里只是为了用作代码提示,实际代码运行还是在设备(开发板)上,设备上也要有对应的包才能正常运行。 + ### Mac 下 + * **方法一**:终端使用 `scp` 命令传输文件到设备上,比如: + ```bash + scp /path/to/your/file.py root@maixcam-xxxx.local:/root + ``` -> 另外,虽然你在电脑上安装了 MaixPy 包,但是由于我们精力有限,我们不确保你能直接在电脑的 Python 导入 maix 包进行使用,请在支持的设备上运行。 + * **方法二**:使用 [FileZilla](https://filezilla-project.org/) 等工具连接设备,将文件传输到设备上,选择 `SFTP` 协议填写设备和账号信息连接即可。 +## 使用图形化积木编程 +开发中,敬请期待。 diff --git a/docs/doc/zh/peripheral/uart.md b/docs/doc/zh/peripheral/uart.md index e69de29b..92f4e623 100644 --- a/docs/doc/zh/peripheral/uart.md +++ b/docs/doc/zh/peripheral/uart.md @@ -0,0 +1,45 @@ +--- +title: MaixPy UART 串口使用介绍 +--- + +## 串口简介 + +串口是一种通信方式,包含了硬件和通信协议的定义。 + +* 硬件包括: + * 3 个引脚: `GND`, `RX`, `TX`,通信双发交叉连接 RX TX, 即一方 TX 发送到另一方的 RX, 双方 GND 连接到一起。 + * 控制器,一般在芯片内部,也叫 UART 外设,一般一个芯片有一个或者多个 UART 控制器,每个控制器有相对应的引脚。 +* 通信协议: 为了让双方能顺利通信,规定了一套协议,具体可以自行学习,常见的参数有 波特率 校验位等,波特率是我们用得最多的参数。 + + +通过板子的串口,可以和其它单片机或者 SOC 进行数据通信,比如可以在 MaixCAM 上实现人体检测功能,检测到坐标后通过串口发送给 STM32 单片机。 + +## MaixPy 中使用串口 + + +对于 MaixCAM 默认从 USB 口引出了一个串口,可以插上配套的 Type-C 转接小板,就能直接使用上面的串口引脚, +也可以不用转接板,直接使用板子上的 `A16(TX)` 和 `A17(RX)`引脚, 和 USB 口引出的是同样的引脚,是等效的。 + + +对于 MaixCAM 使用 USB 引出的串口时需要**注意**,Typc-C 正插和反插,转接小板上的 `RX` 和 `TX`会交换,所以当你发现无法通信时,有可能就是 RX TX 反了,可以尝试将 Type-C 翻转一面插再看看通信是否正常。这个算是设计缺陷,不过一般也不会经常拔插所以适应一下也能接受。 + +将两个通信的板子双方连接好后(通信双发交叉连接 RX TX, 即一方 TX 发送到另一方的 RX, 双方 GND 连接到一起),就可以使用软件了。 + + +通过 MaixPy 使用串口很简单: + +```python +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)) +``` + +先列出了系统的所有串口设备,然后这里使用了第一个,也就是上面说的 Type-C 出 引出的串口。 + +更多串口的 API 请看 [UART API 文档](../../../api/maix/peripheral/uart.md) + +