Ameba MicroPython: Getting Started with RTL8722DM MINI

Required Environment

AmebaD AMB23 board currently supports Windows OS 32-bits and 64-bits (WIN7/8/10), Linux OS (Ubuntu 18 LTS/20 LTS/latest) and macOS operating systems. Please use the latest OS version to have the best experiences. In this documentation, please use the latest version Arduino IDE (at least version 1.8.12).

Introduction to AmebaD AMB23

Ameba is an easy-to-program platform for developing all kind of IoT applications. AmebaD is equipped with various peripheral interfaces, including WiFi, GPIO INT, I2C, UART, SPI, PWM, ADC. Through these interfaces, AmebaD can connect with electronic components such as LED, switches, manometer, hygrometer, PM2.5 dust sensors, …etc.

The collected data can be uploaded via WiFi and be utilized by applications on smart devices to realize IoT implementation.

get-start-1

 PIN nameGPIO INTADCPWMUARTSPII2C
D0GPIOB_0    I2C0 SDA
D1GPIOB_1A4 Serial2_TX  
D2GPIOB_2A5 Serial2_RX  
D3GPIOB_3A6    
D4GPIOB_4A0   
D5GPIOB_5A1  I2C0 SCL*
D6GPIOB_6A2   I2C0 SDA*
D7GPIOB_7A3   
D8GPIOA_2     
D9GPIOA_12 Serial2_TX*SPI1_MOSI 
D10GPIOA_13 Serial2_RX*SPI1_MISO 
D11GPIOA_14   SPI1_CLK 
D12GPIOA_15   SPI1_CS 
D13GPIOA_16     
D14GPIOA_28    
D15GPIOA_18  Serial1_TX*  
D16GPIOA_19  Serial1_RX*  
D17GPIOA_30    
D18GPIOA_21  Serial1_TX  
D19GPIOA_22  Serial1_RX  
D20GPIOA_23    
D21GPIOA_24    
D22GPIOA_31    I2C0 SCL

*: Those functions are not available on MicroPython.

AMB23 has smaller size than Arduino Uno, as shown in the above figure.

get-start-1

AMB23 uses Micro USB to supply power, which is common in many smart devices.
Please refer to the following figure and table for the pin diagram and function of AMB23.

get-start-3

get-start-1

Note: Not all sets of peripherals shown on the picture/table above are available on MicroPython, please refer to “Peripheral Example and API” section for more information.

Introduction to AMB23 MicroPython port

Background Information

MicroPython, by definition, is a lean and efficient Python3 compiler and runtime specially designed for microcontrollers.

MicroPython distinguishes itself from other compilation-based platforms (Arduino etc.) with its powerful method of real-time interaction to Microcontroller through a built-in feature — REPL.

REPL stands for Read-Evaluation-Print-Loop, it is an interactive prompt that you can use to access and control your microcontroller.

REPL has been equipped with other powerful features such as tab completion, line editing, auto-indentation, input history and more. It basically functions like the classic Python IDLE but running on microcontroller.

To use REPL, simply open any serial terminal software (most common ones are teraterm, putty etc.) on your PC and connect to your microcontroller’s serial port, then set baudrate to 115200 before manually reset the board, then you will see >>> MicroPython prompt appear on the terminal. Now you may type in any Python script on REPL as long as it’s support by MicroPython and your microcontroller’s MicroPython port.

Most importantly, try to abuse “help()” function as much as possible to gain more information. For example, upon microcontroller power up and REPL shown, just type

help()
You will see a help page giving you more details about this port; also if you type

help(modules)
it will list out all available builtin modules that are at your disposal

Furthermore, if you want to learn more about a module, such as its API and CONSTANT available, simply type the following code and details of that module will be returned to you,

help(the module of your interest)

Let’s take Pin module (GPIO) as an example:

>>> help(Pin)
object <class 'Pin'> is of type type
  id -- 
  init -- 
  value -- 
  off -- 
  on -- 
  toggle -- 
  board -- <class 'board'>
  IN -- 0
  OUT -- 1
  PULL_NONE -- 0
  PULL_UP -- 1
  PULL_DOWN -- 2

REPL Hotkeys

• Ctrl + d :
Soft reboot MicroPython will perform software reboot, this is useful when your microcontroller is behaving abnormally. This will also run scripts in ‘boot.py’ once again. Note that this will only reset the MicroPython interpreter not the hardware, all your previously configured hardware will stay the way it is until you manually hard-reset the board.

• Ctrl + e :
Paste mode allow you to perform pasting a large trunk of code into REPL at once without executing code line by line. This is useful when you have found a MicroPython library and wish to test it out immediately by copy and paste.

• Ctrl + b :
Normal mode This hotkey will set REPL back to normal mode. This is useful if you are stuck in certain mode and can not get out.

• Ctrl + c :
Quick cancel This hotkey help you to cancel any input and return a new line.

Setting up Development Environment

Step 1. Installing the Driver

First, connect AmebaD to the computer via Micro USB:

get-start-1

If this is the first time you connect AmebaD to your computer, the USB driver for AmebaD will be automatic installed.
You can check the COM port number in Device Manager of your computer:

get-start-1

Step 2. Installing the necessary tools

On Windows

For windows users, please install a serial terminal software to interact with MicroPython. The most common serial terminals are Tera Term and Putty, here we recommend using Tera Term, which can be downloaded from internet.

For advanced developer who wish to compile MicroPython firmware from scratch, then please be sure to install Cygwin, which is a Linux-like environment running on Windows system. When selecting the Cygwin installer, we recommend using the Cygwin 32-bit version. During Cygwin installation, installer will prompt user if wish to install other software, please make sure to select the GNU version of make from the Devel category (see picture below) and pick the latest edition.

get-start-1

Also, Python3 is required during firmware compilation, so be sure to download the latest Python3 from its official website and have it added as environment variable when asked during installation.

On Linux

For Linux user, please install a serial terminal software of your choice using apt-get install command. Here we recommend using picocom for its lightweight.

For advanced developer interested in developing MicroPython module in C, please make sure the GNU make of at least version 3.82 or newer and Python3 are installed and can be found using terminal.

Upload Firmware into Ameba

Step 1. Navigate to “Release” folder

After downloading the MicroPython repository from Github, you will notice a “Release” folder in the root directory of this repository, enter this folder and locate a tool named “Double-Click-Me-to-Upload”.

Step 2. Enter UART Download mode

To do this, first press and hold the UART_DOWNLOAD button, then press the RESET button.

get-start-1

Step 3. Run “Double-Click-Me-to-Upload”

As the name suggested, double click on the file to run it, follow instructions printed on the screen to update the ameba’s serial COM port (this is known to us during the driver installation step mentioned above) so the uploading can be carried out successfully. Once the uploading is successful, you will see a line of log printed on the screen – “All images are sent successfully”

Try the First Example

Step 1. Open REPL

REPL stands for Read, Evaluate, Print and Loop, it is the MicroPython’s terminal for user to control the microcontroller. REPL is running on LOG UART, thus we need to open our serial terminal software, in this case, Tera Term to see REPL,

get-start-1

Once Tera Term is opened, select “Serial” like in the picture above and choose your ameba’s serial port using the dropdown list, after that, hit “OK”. If your serial terminal is not configured to 115200 baud rate, now is the time to change it to 115200 and leave the rest of settings as default.

Now that the serial port is connected, press the RESET button once on your ameba and you should see the MicroPython’s welcome page as shown below,

get-start-1

What happened here was that your Ameba first check its calibration data and then boot into MicroPython’s firmware, MicroPython then run the “boot.py” python script and imported all the built-in libraries so we can quickly start coding.

Now, you can simply type :

help() to see more information, and type

help(modules) to check all readily available libraries

Step 2. Run WiFi Scan example

As most of peripherals’ examples requires additional hardware to show the example is working, we will just use WiFi Scan example as our first example and to see how easy it is to control WiFi using MicroPython.

Now, simply type help(). You should be able to see this:

get-start-1

Then simply copy the code highlighted in the red box and paste to REPL then Enter, you should be able to see the returned result with all discovered wireless network in your surrounding.

get-start-1

With this, we can be sure that the MicroPython firmware is correctly compiled and installed.

Please confirm that QQ communication software is installed